block; COLOR is an optional
argument indicating the background colour of the resulting block.\"
(insert \"\n#+html:\"
(format \"" . buffer-flip-forward)
("M-S-" . buffer-flip-backward)
("C-g" . buffer-flip-abort))
:config
(setq buffer-flip-skip-patterns
'("^\\*helm\\b")))
;; key to begin cycling buffers.
(global-set-key (kbd "M-") 'buffer-flip)
#+END_SRC
See [[https://www.emacswiki.org/emacs/buffer-move.el][buffer-move]] if you're interested in moving the buffers, and their windows,
into new configurations.
** TODO COMMENT Web Development :Disabled:
:PROPERTIES:
:CUSTOM_ID: COMMENT-Web-Development
:END:
First, let's get some useful Cheat Sheets...
#+begin_src emacs-lisp
;; Get the repos locally, and use: M-x my/cheatsheet to view the pretty HTML sheets.
(mapcar #'my/cheatsheet '("JavaScript" "Vue" "AngularJS"))
#+end_src
*** Quickly produce HTML from CSS-like selectors
:PROPERTIES:
:CUSTOM_ID: Quickly-produce-HTML-from-CSS-like-selectors
:END:
Emmet-mode (outside of Emacs, this is known as [[https://emmet.io/][Emmet]] and [[https://www.smashingmagazine.com/2009/11/zen-coding-a-new-way-to-write-html-code/][Zen Coding]]),
is a powerful abbreviation engine that expands CSS selectors into HTML code.
It's a neat way to write markup quickly in Emacs.
# Alternative example candidate: div#news.module>div.header+div.body>ul>li#item-$*5
#
Watch this [[https://vimeo.com/7405114][demo video]]. Or here's an example with filler text:
=#page>.logo+ul#navigation>li*5>a>lorem3=
expands into
# =div#page>div.logo+ul#navigation>li*5>a=
#+begin_src html :tangle no
#+end_src
Likewise, we can make 5 links next to 5 input boxes with:
~(a[href=www.google.ca]{Click me!}+label{Name:}>input[value="first name"])*5~.
Anyhow, here's my setup:
#+begin_src emacs-lisp
;; USAGE: Place point in an emmet snippet and press C-j to expand it to appropriate tag structure;
;; e.g., #q.x>p C-j. Alternatively, press C-j then start typing an emmet snippet to see it preview live.
;; [C-j is just M-x emmet-expand-line]
;;
(use-package emmet-mode ;; C-j ! RET === Makes an entire HTML template for you.
:hook (web-mode . emmet-mode))
;;
;; Please show me an HTML expansion preview as I type
(setq emmet-preview-default t) ;; Press C-j then start typing; e.g., C-j #q.x.y>p>b RET
;;
;; After expanding, positioned the cursor between first empty quotes.
;; The preview can help with tricky CSS precedence rules; e.g., C-j gives the same thing for: a>b+c>d == a>(b+(c>d))
(setq emmet-move-cursor-between-quotes t) ;; E.g., C-j #q[name] RET
;;
(add-hook 'sgml-mode-hook 'emmet-mode) ;; Auto-start on any markup modes
;; (add-hook 'css-mode-hook 'emmet-mode) ;; enable Emmet's css abbreviation.
#+end_src
#+begin_details Notable HTML key bindings (including [[https://www.gnu.org/software/emacs/manual/html_node/emacs/HTML-Mode.html][built-ins]])
+ Wrap with Abbreviation / C-c C-c w :: Select a region, then enter an abbreviation.
- For example, select the phrase ~Hello, World!~ then ~C-c C-c w q>b~ to place that phrase in a quote, and make it bold.
+ Go to Edit Point / C-M-{Leftarrow, Rightarrow} :: to move between editable-tags/empty-attributes. ([[https://docs.emmet.io/actions/go-to-edit-point/][Demo]])
+ C-c TAB :: Cheaply preview the HTML file by toggling visibility of tags.
+ C-c /, C-c C-e :: Insert a close tag for the innermost unterminated tag (sgml-close-tag). If called within a tag or a comment, close it instead of inserting a close tag.
+ C-c ? tag RET :: Display a description of the meaning of tag tag (sgml-tag-help). If the argument tag is empty, describe the tag at point. :fire:
+ C-c C-d :: Delete the tag at or after point, and delete the matching tag too (sgml-delete-tag). If the tag at or after point is an opening tag, delete the closing tag too; if it is a closing tag, delete the opening tag too.
+ C-c C-f/b :: More 'f'orward or 'b'ackward one tag element. ---Nice way to quicly check that your tags are balanced as you think they are.
+ C-c C-a :: Interactively insert attribute values for the current tag. :fire:
- Super helpful when you don't remember the possible attributes of a tag, or their possible values.
# - E.g., within ~![]()
~ press ~C-c C-a~ then ~id~ then ~hola~ then ~RET~ then ~C-g~.
- C-c C-t :: Interactively specify a tag and its attributes!
#+end_details
#+begin_details Notable Emmet Features & Examples
+ Example that includes Ids, classes, children, sibling selectors,
{content}, 10 random lorem text, parenthesis for grouping; as well
as attributes with and without values.
#+begin_src html :tangle no
ParentTag#Id.Class1.Class2[Attribute1 Attribute2]>ChildTag{hiya there}>lorem10+(GrandChild1>GreatGrandChild11)+GrandChild2#Id2[attribute=value]
#+end_src
+ Nesting (>) can be 'undone' with "climb-up"(^): ~a>b>c>d^^e~ == ~a>(b>c>d)+e~
+ Multiplication is repeated addition: ~X*3>Y~ == ~(X>Y)+(X>Y)+(X>Y)~
+ In general, ~loremN~ produces $N$ many random filler text. E.g., make a dummy list: =ul>li*3>lorem3=
Other notable snippets include
=a#neato.x.y.z, input[hola=value], img, p, table+, ul+, ol+=.
+ There are also [[https://docs.emmet.io/css-abbreviations/][CSS abbreviations]]; but that's a story for another time.
+ This [[https://docs.emmet.io/cheat-sheet/][cheat sheet]] has all the supported abbreviations, with expansions.
--------------------------------------------------------------------------------
+ ID and CLASS attributes: =div#page.section.main=
- ~div~ tag name can be omitted when writing element starting from ID or CLASS:
~#content>.section~ is the same as ~div#content>div.section~.
+ Custom attributes: ~div[title], a[title="Hello world" rel], td[colspan=2]~
+ Element multiplication: ~li*5~ will output ~~ tag five times.
+ Item numbering with the ~$~ character: ~li.item$*3~ will output ~ ~ tag
three times, replacing ~$~ character with item number.
+ Multiple ~$~ characters in a row are used as zero padding, i.e.: ~li.item$$$~ → ~li.item001~
+ Abbreviation groups with unlimited nesting:
~div#page>(div#header>ul#nav>li*4>a)+(div#page>(h1>span)+p*2)+div#footer~
- You can literally write a full document markup with just a single line.
+ Text support: ~p>{Click }+a{here}+{ to continue}~.
--------------------------------------------------------------------------------
Good tutorials:
+ [[https://jonchristopher.us/blog/the-art-of-zen-coding-bringing-snippets-to-a-new-level/][The Art of zen-coding: Bringing Snippets to a New Level - Jon Christopher]]
+ [[https://www.smashingmagazine.com/2009/11/zen-coding-a-new-way-to-write-html-code/][Zen Coding: A Speedy Way To Write HTML/CSS Code — Smashing Magazine]]
+ [[https://www.smashingmagazine.com/2013/03/goodbye-zen-coding-hello-emmet/][Goodbye, Zen Coding. Hello, Emmet! — Smashing Magazine]]
#+end_details
For more on writing HTML within Emacs, see this ~2min /yet very
informative/ [[https://www.youtube.com/watch?app=desktop&v=sBhQ2NIcrLQ&ab_channel=emacsrocks][video]] by /Emacs Rocks!/
Let's add a new snippet so that: ~angular C-j C-c C-v~ shows us an interactive web
application.
#+begin_src emacs-lisp
(cl-defun my/add-emmet-snippet (abbreviation expansion)
"Add ABBREVIATION as a snippet in `emmet-mode' to be EXPANSION.
Both arguments are strings."
(add-hook 'emmet-mode-hook
;; [Should this be added to “emmet-snippets” variable instead?]
`(lambda () (puthash ,abbreviation ,expansion emmet-tag-snippets-table))))
(setq emmet-mode-hook nil)
(my/add-emmet-snippet "vue"
"
Salamun Alaykum, world!
")
(my/add-emmet-snippet "angular"
"
Salamun Alaykum, world!
")
#+end_src
A non-blocking alternative to the built-in ~alert()~:
#+begin_src emacs-lisp
;; A way to show results of trying things out ---when not using a reactive framework.
(my/add-emmet-snippet "message"
" // Append “text” node to the end of tag with “id”.
// Example:
function message(id, text = \"Hello, world\") {
const tag = document.createElement(\"p\") //
const textNode = document.createTextNode(text)
tag.appendChild(textNode); // " . emr-show-refactor-menu)))
;; Useful refactors
;; ⇒ delete unused let binding form
;; ⇒ eval and replace
;; ⇒ extract constant ★
;; ⇒ extract function / inline function
;; ⇒ extract to let ★★ / inline let variable
;; ⇒ extract variable / inline variable
;; ⇒ implement function ★
;; ⇒ comment / uncomment region
;; ★ Some refactors need to be rigged via M-x; e.g., on a symbol run “M-x emr
;; impl” to get a template to implement it as a function.
;; ★★ Some need to be against a form: Either before the starting paren, or else a selected region.
(😴 progn
;; It seems easy to add more refactorings:
;; https://github.com/Wilfred/emacs-refactor?tab=readme-ov-file#user-content-extension
;;
;; Let's add one!
;;
(emr-declare-command 'emr-el-tidy-requires
:title "tidy"
:description "require"
:modes 'emacs-lisp-mode
:predicate (lambda ()
(thing-at-point-looking-at
(rx bol (* space) "(require " (* nonl)))))
(defun emr-el-tidy-requires ()
"Consolidate and reorder requires in the current buffer.
Order requires alphabetically and remove duplicates."
(interactive "*")
(let (requires
(rx-require (rx bol (* space) "(require" (+ space)
(group-n 1 (+ (not space)))
")")))
(save-excursion
(when (emr-el:goto-first-match rx-require)
(beginning-of-line)
(forward-line)
;; Collect requires in buffer.
(save-excursion
(goto-char (point-min))
(while (search-forward-regexp rx-require nil t)
(push (substring-no-properties (match-string 1))
requires)
(replace-match "")
(when (emr-blank-line?)
(ignore-errors
(kill-line)))))
(->> (emr-el:sort-requires requires)
(s-join "\n")
(s-append "\n")
(insert))))))
(defun emr-el:sort-requires (requires)
(->> (sort requires (lambda (L R) (string< L R)))
(-distinct)
(--map (s-trim it))
(--map (format "(require %s)" it))))
;; Let's provide an alias for a useful method.
(defalias 'emr-el-rename-in-file 'emr-iedit-global)
;; More Lisp-specific refactoring ideas ---such as changing “if” to “cond”---
;; can be found by looking at RedShank:
;; https://github.com/emacsattic/redshank/blob/d059c5841044aa163664f8bf87c1d981bf0a04fe/redshank.el#L745
;; WAIT, it seems that these work fine with Emacs Lisp, not just Common Lisp! 😲
;; NOTE: Lispy already includes some common refactorings like extract function and cond<->if out of the box.
)
#+end_src
Inactivity does not mean it's not working. At least for [[http://www.foldr.org/~michaelw/emacs/redshank/][redshank]] I can confirm
it does work.
As you correctly observe, some 'refactorings' are just rejuggling of
s-expressions.
So if you use a structural editing package like [[http://mumble.net/~campbell/emacs/][paredit]] or [[https://github.com/abo-abo/lispy][lispy]], they are just
an adhoc key macro away. Lispy already includes some common refactorings like
extract function and cond<->if out of the box.
--------------------------------------------------------------------------------
+ You're looking for a lexically intelligent rename function - one that renames
variables by their scope, not just a dumb find and replace. Packages like
this exist for a lot of languages but as of writing (April 2019), there aren't
actually many options for Emacs Lisp. The [[https://melpa.org/#/erefactor][erefactor]] package is the only one I
know of.
=erefactor-rename-symbol-in-buffer= is the function you want. It's an
intelligent find-and-replace command that will replace symbols in the current
scope (including docstrings). The limitation of this command is that it won't
search outside the current buffer. It's smart, but not perfect. It will ask
you to confirm each occurance to ensure the end result is sanitary.
#+begin_src emacs-lisp
(use-package erefactor)
;;* Level 1
;;** Level 2
;;*** Level 3
;; https://melpa.org/#/redshank
;; Redshank is a collection of code-wrangling Emacs macros mostly geared towards
;; Common Lisp, but some are useful for other Lisp dialects, too. It's built on top of Paraedit.
;;
;; Some mild (Common Lisp) refactoring support:
;; ⇒ Semantics-preserving rewriting of forms (IF to COND, WHEN NOT to UNLESS, etc.)
;; ⇒ Extracting marked regions to DEFUNs, with free variables becoming arguments of the extracted function
;; ⇒ Extracting forms to LET-bound variables of the nearest enclosing LET block
;;
;; There's a lot of cool stuff in here. I especially like "redshank-align-forms-as-columns"; it's really useful for all lisps.
(use-package redshank)
;; ⇒ (redshank-align-forms-as-columns BEG END)
;; ⇒ redshank-condify-form Transform a Common Lisp IF form into an equivalent COND form.
;; ⇒ redshank-enclose-form-with-lambda Enclose form with lambda expression with parameter VAR.
;; Cursor should be inside a form.
;; ⇒ redshank-extract-to-defun Extracts region from START to END as new defun NAME.
;; ⇒ redshank-rewrite-negated-predicate Rewrite the negated predicate of a WHEN or UNLESS form at point.
(use-package lispy
:hook emacs-lisp)
;;; The price for these short bindings is that they are only active when point is before/after a parens, or when the region is active.
;;;
;; The advantage of short bindings is that you are more likely to use them. As you use them more, you learn how to combine them, increasing your editing efficiency.
;; Select a region then press ", it's smart enough to escape any quotes inside the region or to escape new quotes if we're already in a string.
;; Use C-u " on a region to remove the quotes.
;; Select a region then press ( or ) to enclose it in parens, then use / at a parens to remove them.
;; In Lisp jargon, this is “splicing”.
;; C-k now means “kill until end of form”; e.g., (f x | y z) ⇒ (f x)
;; DEL means delete form
;; “ ; ” now means comment current (possibly multi-line) expression
;;; c ⇒ clone form
;;; e ⇒ eval form
;;; E ⇒ eval & insert
;; d ⇒ jump to different side of from, i.e., exchange mark. Quickly jump between start & end of form.
;;; F/D ⇒ jump to definition of form head; e.g., (f x y)|F ⇒ jumps to definition of f
;;; C-1 ⇒ Toggle inline docstring for form head 💝
;;; (Use “xh” to get the docstring in a help buffer)
;;; C-2 ⇒ Toggle inline argslist for form head 💝
;; xk/xd ⇒ Extract form to new ‘d’efun bloc‘k’ 💝
;; xb ⇒ ‘b’ind form to new let clause
;; x? ⇒ See possible completions
;; xs ⇒ C-x C-s
;;; C ⇒ Convolute: (f (g ∣(h x))) ⇒ (g (f ∣(h x)))
(use-package lispy)
;;; There's a lot to remember, so make "x" show me what I can do!
(when (fboundp 'lispy-define-key)
(lispy-define-key lispy-mode-map "x"
(pretty-hydra-define my/hydra-lispy-x (:exit t)
("Refactor"
(("b" lispy-bind-variable "bind variable")
("u" lispy-unbind-variable "unbind let-var")
("c" lispy-to-cond "if → cond")
("i" lispy-to-ifs "cond → if")
("d" lispy-to-defun "λ → 𝑓")
("l" lispy-to-lambda "𝑓 → λ")
("D" lispy-extract-defun "extract defun")
(">" lispy-toggle-thread-last "toggle last-threaded form")
;; ("t" lispy-toggle-thread-last "toggle last-threaded form")
;; ("k" lispy-extract-block "extract block")
("f" lispy-flatten "flatten")
("F" lispy-let-flatten "let-flatten"))
"Evaluate"
(("v" lispy-eval-expression "eval")
("r" lispy-eval-and-replace "eval and replace")
("H" lispy-describe "describe in *help*")
("h" lispy-describe-inline "describe inline")
;; ("j" lispy-debug-step-in "debug step in")
("m" lispy-cursor-ace "multi cursor")
("s" save-buffer)
("t" lispy-view-test "view test")
("T" lispy-ert "ert")
;; ("w" lispy-show-top-level "where")
;; ("B" lispy-store-region-and-buffer "store list bounds")
;; ("R" lispy-reverse "reverse")
)))))
; (my/hydra-lispy-x/body)
; (cl-inspect '(+ 2 (print 40)))
;; “a 𝓍” to mark a subform, or “𝓃 m”, then “C-1” to toggle its docs inline. Only one doc visible at a time.
; (list #'message #'identity #'mapcar)
;; f/b ⇒ move forward/backward between forms
;; f/b ⇒ move forward/backard between forms
;;; xd ⇒ replace lambda with defun (saved to kill ring!)
;;; xc ⇒ replace arbitrarly nested IFs to COND 😻
;;; xi ⇒ replace COND with nested IFs
;;; x> ⇒ toggle between `thread-last` and equivalent expression
;;; xf ⇒ inline macro call, e.g., (thread-last f e) ⇒ (f e)
;;; xr ⇒ eval form & replace
;; ;;; M/O ⇒ format into multiple / One line
;; ;;; i ⇒ prettify code; e.g., removing extra whitespace
;; ;;; w/s ⇒ move a form left/right
;; ;;; a ⇒ jump to a subform
;; ;;; t ⇒ “teelport” / relocate current form to a specific location, tt to teleport anywhere in buffer
;; ;;; N/W ⇒ narrow/widen to form
;; v ⇒ view current form at top of screen, this is a toggle
;; Slurp & barf:
;; Slurp >: Current form slurps up the next form, i.e., (f)| (x) ⇒ (f (x))
;; and (f) |(x) ⇒ (f (x)). That is, slurping at a boundary means use this form as the enclosing form
;; and so the other argument of the slurp retains its parens.
;;
;; Barf: Throw out the first/last sexp in a form, depending on whether < is pressed at the start or end of the form.
;; |(a b c) ⇒ a (b c) & (a b c)| ⇒ (a b) c
;;
;; Barf is useful in conjunction with `d`.
;; xT ⇒ run all tests; i.e., “M-x ert t”
;; u ⇒ undo most recent change to buffer.
;; Full docs @ https://web.archive.org/web/20190924092330/http://oremacs.com/lispy/#lispy-shifttab
#+end_src
+ I would suggest just using =projectile-replace=.
--------------------------------------------------------------------------------
TODO Things to read
+ [ ] [[https://lispcookbook.github.io/cl-cookbook/debugging.html][CL Debugging]]
+ [ ] [[https://lispcookbook.github.io/cl-cookbook/emacs-ide.html#editing-with-parentheses][Using Emacs as an IDE]]
+ [ ] [[https://github.com/Fuco1/smartparens][GitHub - Fuco1/smartparens: Minor mode for Emacs that deals with parens pairs and tries to be smart about it.]]
+ [ ] [[https://github.com/promethial/paxedit/tree/48df0a26285f68cd20ea64368e7bf2a5fbf13135][GitHub - promethial/paxedit at 48df0a26285f68cd20ea64368e7bf2a5fbf13135]]
+ [ ] [[https://howardabrams.com/hamacs/ha-programming-elisp.html#org0313769][Lispy Configuration]]
+ [ ] [[https://emacs.stackexchange.com/questions/32733/emacs-lisp-refactoring-add-variable-to-surrounding-let][Emacs lisp refactoring - add variable to surrounding let - Emacs Stack Exchange]]
+ [ ] [[https://thewanderingcoder.com/2015/02/refactoring-beginning-emacs-lisp-i-adding-tests/][Refactoring “Beginning Emacs Lisp”: I: Adding Tests | Sean Miller: The Wandering Coder]]
+ [ ] [[https://thewanderingcoder.com/2015/02/refactoring-beginning-emacs-lisp-ii/][Refactoring “Beginning Emacs Lisp”: II | Sean Miller: The Wandering Coder]]
+ [ ] [[https://thewanderingcoder.com/2015/02/emacs-lisp-adding-tests-ert-runner-and-overseer/][Emacs Lisp: Adding Tests: ert-runner and overseer | Sean Miller: The Wandering Coder]]
+ [ ] [[https://github.com/emacs-elsa/Elsa?tab=readme-ov-file][GitHub - emacs-elsa/Elsa: Emacs Lisp Static Analyzer and gradual type system.]]
+ [ ] [[https://isamert.net/2023/08/14/elisp-editing-development-tips.html#m-x-ielm][Elisp editing/development tips | isamert.net]]
+ [ ] [[https://github.com/alphapapa/emacs-package-dev-handbook?tab=readme-ov-file#debugging][@ #debugging - alphapapa/emacs-package-dev-handbook: An Emacs package development handbook. Built with Emacs, by Emacs package developers, for Emacs package developers.]]
+ [ ] [[https://200ok.ch/posts/2020-10-01_introduction_to_profiling_in_emacs.html][Introduction to profiling in Emacs]]
+ [ ] [[https://www.dotemacs.de/recovery.html][How to avoid errors in your dotfile]]
+ [ ] [[https://irreal.org/blog/?p=6508][Emacs Lisp Development Tools | Irreal]]
+ [ ] https://www.reddit.com/r/emacs/comments/10bcvkk/elisp_language_server/
+ [ ] [[https://emacs.stackexchange.com/questions/2949/what-are-good-tools-for-emacs-package-development][elisp - What are good tools for Emacs package development? - Emacs Stack Exchange]]
** COMMENT Are there any errors in my code?
:PROPERTIES:
:CUSTOM_ID: Are-there-any-errors-in-my-code
:END:
[[https://www.flycheck.org/en/latest/][Flycheck]] gives us syntax checking and linting tools to automatically check the
contents of buffers while you type, and reports warnings and errors directly in
the buffer, or in an optional error list. Sadly, the default reporting of errors
looks like ~FlyC 3~ in the modeline, but with [[https://github.com/liblit/flycheck-status-emoji][flycheck-status-emoji]] we can see the
status using cute & compact emoji such as ~😱3~.
#+begin_src emacs-lisp
(use-package flycheck-status-emoji
:config
(load-library "flycheck-status-emoji")
;; (diminish-undo 'flycheck-mode)
(flycheck-status-emoji-mode))
#+end_src
Let's also have a nifty modal menu to quickly navigate between errors.
#+begin_src emacs-lisp
(use-package helm-flycheck)
(bind-key*
"C-c !"
(defhydra my/flycheck-hydra (:color blue :hint nil)
"Move around flycheck errors and get info about them"
("n" flycheck-next-error "next" :column "Navigation")
("p" flycheck-previous-error "previous")
("f" flycheck-first-error "first")
("l" flycheck-list-errors "list")
("h" helm-flycheck "helm") ;; Jump to an error / see-errors from a nice interactive menu
("e" flycheck-explain-error-at-point "explain" :column "Current errror")
("c" flycheck-copy-errors-as-kill "copy")
("d" flycheck-describe-checker "Describe checker" :column "More")
("s" flycheck-select-checker "Select checker")
("S" flycheck-verify-setup "Suggest setup")
("m" flycheck-manual "manual")))
#+end_src
*** On the fly syntax checking
:PROPERTIES:
:CUSTOM_ID: On-the-fly-syntax-checking
:END:
[[https://www.flycheck.org/en/latest/][Flycheck]] is a on-the-fly syntax checker that relies on external programs to
check buffers; which must be installed separately.
+ E.g., ghc is required for Haskell; whereas Emacs Lisp is checked by Emacs'
own byte compiler, ~emacs-lisp~.
+ Sometimes more than one checking tool applies, use ~C-c ! s~ to select a
different checker.
+ =C-c ! n,p,l= takes you to the ‘n’ext or ‘p’revious
error, or ‘l’ist all errors in another buffer.
~C-c ! c~ to explicitly recheck the buffer.
#+begin_src emacs-lisp
(use-package flycheck
:init (global-flycheck-mode)
:config ;; There may be multiple tools; I have GHC not Stack, so let's avoid that.
(setq-default flycheck-disabled-checkers '(haskell-stack-ghc emacs-lisp-checkdoc))
:custom (flycheck-display-errors-delay .3))
#+end_src
In an org-src block, we press ~C-c '~ to get into the language's mode where
flycheck will provide warnings.
#+begin_src haskell :tangle no
module Main where
main :: IO ()
main = putStrLn $ "nice" ++ f 0
f :: Int -> String
f x = x -- show x
-- type error
#+end_src
In-general, flycheck is intended for self-contained raw code ---not for source
blocks in Org-mode. Whence, the above example is a complete Haskell program,
with a named module and ~main~ method.
I think the built-in [[https://www.gnu.org/software/emacs/manual/html_node/emacs/Flymake.html][flymake]] syntax checker is better for Emacs Lisp,
so let's use that for ELisp.
#+BEGIN_SRC emacs-lisp
(use-package flymake
:hook ((emacs-lisp-mode . (lambda () (flycheck-mode -1)))
(emacs-lisp-mode . flymake-mode))
:bind (:map flymake-mode-map
("C-c ! n" . flymake-goto-next-error)
("C-c ! p" . flymake-goto-prev-error)))
#+END_SRC
Try it out:
#+begin_src emacs-lisp :tangle no
(setq 1 2) ;; Error: ‘1’ is not a variable.
#+end_src
** Finally, for authoring to MELPA
:PROPERTIES:
:CREATED: [2025-08-28 Thu 20:22]
:END:
#+begin_src emacs-lisp
(use-package flycheck :defer t)
;; Checker for ELisp package meta-data.
;; This makes use of “package-lint”, which is a prerequisite for MELPA.
(use-package flycheck-package
:hook (emacs-lisp . my/enable-flycheck-when-I-am-authoring-for-MELPA))
(cl-defun my/enable-flycheck-when-I-am-authoring-for-MELPA ()
(unless (or (s-starts-with? "*Org Src init.org[ emacs-lisp ]*" (buffer-name))
(equal default-directory (f-expand user-emacs-directory)))
(flycheck-package-setup)
(flycheck-mode +1)))
#+end_src
* Cosmetics
:PROPERTIES:
:CUSTOM_ID: Cosmetics
:header-args: :tangle init.el
:END:
Upon startup, we want to be greeted with a useful, yet unobtrusive, message
briefly detailing major system details. Moreover, the bottom-most area of the
screen should display battery life, data, & time. Likewise, we may have a casual
file explorer ---primarily to show-off to newcomers, since great functionality
is found with ~M-x dired~ ---doc:dired.
#+BEGIN_SRC emacs-lisp :tangle init.el
;; Get org-headers to look pretty! E.g., * → ⊙, ** ↦ ◯, *** ↦ ★
;; https://github.com/emacsorphanage/org-bullets
(use-package org-bullets :hook (org-mode . org-bullets-mode))
#+END_SRC
** Emojis
:PROPERTIES:
:CREATED: [2024-11-08 Fri 18:16]
:END:
#+begin_src emacs-lisp
(if (member "Apple Color Emoji" (font-family-list))
(set-fontset-font t 'unicode "Apple Color Emoji" nil 'prepend)
(message-box "Musa: Install the font!"))
;; E.g., Download font such as https://fonts.google.com/noto/specimen/Noto+Color+Emoji
;; Double-click on the ttf file then select “install” to have it installed on your system
;; (Note: Noto does not work on my personal machine.)
;; Render ASCII such as " :-) " as emoji 🙂.
(use-package emojify)
(when (fboundp 'global-emojify-mode)
(setq emojify-display-style 'unicode) ;; unicode is the way to go!
(setq emojify-emoji-styles '(unicode))
(global-emojify-mode 1)) ;; Will install missing images, if need be.
#+end_SRC
** Startup message: Emacs & Org versions
:PROPERTIES:
:CUSTOM_ID: Startup-message-Emacs-Org-versions
:END:
Let's always welcome ourselves when Emacs begins with a helpful message. For
example, which user account is running and what are the version numbers of our
primary tools.
#+begin_src emacs-lisp
;; Silence the usual message: Get more info using the about page via C-h C-a.
(setq inhibit-startup-message t)
;; Open my-life.org on startup instead of *scratch*
(setq initial-buffer-choice
(lambda ()
(let ((buf (find-file-noselect "~/Dropbox/my-life.org")))
(with-current-buffer buf
(font-lock-update))
buf)))
(defun display-startup-echo-area-message ()
"The message that is shown after ‘user-init-file’ is loaded."
(message
(concat "Welcome " user-full-name
"! Emacs " emacs-version
"; Org-mode " org-version
"; System " (symbol-name system-type)
"/" (system-name)
"; Time " (emacs-init-time))))
#+end_src
Now my startup message is,
#+begin_example
Welcome Musa Al-hassy! Emacs 27.1; Org-mode 9.4.4; System darwin/Musas-MacBook-Air.local; Time 13.331914 seconds
#+end_example
:Manually_Computing_Init_Time:
#+BEGIN_SRC emacs-lisp :tangle no
(format "; Time %.3fs"
(float-time (time-subtract (current-time) before-init-time)))
#+END_SRC
:End:
Let's change the Emacs frame to mention the name of the buffer in focus,
as well as a nice ‘motto’:
#+begin_src emacs-lisp
;; Keep self motivated!
(setq frame-title-format '("" "%b - Living The Dream (•̀ᴗ•́)و"))
#+end_src
** My to-do list: The initial buffer when Emacs opens up
:PROPERTIES:
:CUSTOM_ID: My-to-do-list-The-initial-buffer-when-Emacs-opens-up
:END:
I almost always have Emacs open; I don't need a dashboard, but would like to see
my to-do list and my init file, side-by-side.
#+BEGIN_SRC emacs-lisp
;; I have symlinks for various things, just follow them, do not ask me.
(setq vc-follow-symlinks t)
;; After my settings have been loaded, e.g., fancy priorities
;; and cosmetics, then open my notes files.
(when nil add-hook 'emacs-startup-hook
(lambda ()
(-let [my-life.el (getenv "MY_LIFE_ELISP")]
(unless org-default-notes-file
(error "Add to .zshrc “ export MY_LIFE_ELISP=\"/full/path/to/my-life.el\" ”, then load my-life.el"))
(load-file my-life.el))))
#+END_SRC
There is the neat-looking [[https://github.com/emacs-dashboard/emacs-dashboard][emacs-dashboard]] package that provides an extensbile
yet minimalist splash screen showing recent files, projects, and bookmarks.
** A sleek, informative, & fancy mode line
:PROPERTIES:
:CUSTOM_ID: A-sleek-informative-and-fancy-mode-line
:END:
The ‘modeline’ is a part near the bottom of Emacs that gives information about
the current buffer, such as its file-type/‘major-mode’ and enabled
extensions/‘minor-modes’. Let's use the [[https://github.com/seagle0128/doom-modeline][doom-modeline]], which is a /sleek &
minimalistic, yet fancy/ setup with the following notable perks:
+ Gives each buffer a nice icon in the modeline (denoting its major mode; e.g.,
Lisp/JavaScript/Org/etc each get a cool icon).
+ Name of file becomes red when unsaved/modified.
+ Nice version control icon, with branch name.
+ Name of file is of the shape is shown as “project/file.ext”, when a project
is detected using ~projectile.el~.
+ Flycheck error reporting is ugly by default, and one would consider using
flycheck-status-emojis to make things look better in a simple modeline, but
Doom-modeline gives a nice status indicators for Flycheck.
+ Shows “+2” when the text scale is two above usual.
For fine-grained control on what/how things appear, there is
doc:doom-modeline-def-modeline and doc:doom-modeline-set-modeline.
NOTE: We need to run =M-x= doc:nerd-icons-install-fonts for doom-modeline to use pretty icons ---then restart Emacs.
#+begin_src emacs-lisp :tangle init.el
;; The modeline looks really nice with doom-themes, e.g., doom-solarised-light.
(use-package doom-modeline
:config (doom-modeline-mode))
;; Use minimal height so icons still fit; modeline gets slightly larger when
;; buffer is modified since the "save icon" shows up. Let's disable the icon.
;; Let's also essentially disable the hud bar, a sort of progress-bar on where we are in the buffer.
(setq doom-modeline-height 21)
(setq doom-modeline-buffer-state-icon nil)
(setq doom-modeline-hud t)
(setq doom-modeline-bar-width 1)
;; Show 3 Flycheck numbers: “red-error / yellow-warning / green-info”, which
;; we can click to see a listing.
;; If not for doom-modeline, we'd need to use flycheck-status-emoji.el.
(setq doom-modeline-checker-simple-format nil)
;; Don't display the buffer encoding, E.g., “UTF-8”.
(setq doom-modeline-buffer-encoding nil)
;; Inactive buffers' modeline is greyed out.
;; (let ((it "Source Code Pro Light" ))
;; (set-face-attribute 'mode-line nil :family it :height 100)
;; (set-face-attribute 'mode-line-inactive nil :family it :height 100))
;; A quick hacky way to add stuff to doom-modeline is to add to the mode-line-process list.
;; E.g.: (add-to-list 'mode-line-process '(:eval (format "%s" (count-words (point-min) (point-max)))))
;; We likely want to add this locally, to hooks on major modes.
#+end_src
:Disabled__spaceline_modeline:
[[https://github.com/TheBB/spaceline][Spaceline]]
# I may not use the spacemacs [[https://www.emacswiki.org/emacs/StarterKits][starter kit]], since I find spacemacs to “hide things”
# from me ---whereas Emacs “encourages” me to learn more---, however it is a
# configuration and I enjoy reading Emacs configs in order to improve my own
# setup. From Spacemacs I've adopted Helm for list completion, its sleek light &
# dark themes, and its modified powerline setup.
#+begin_src emacs-lisp :tangle no
;; When using helm & info & default, mode line looks prettier.
(use-package spaceline
:custom (spaceline-buffer-encoding-abbrev-p nil)
;; Use an arrow to seperate modeline information
(powerline-default-separator 'arrow)
;; Show “line-number : column-number” in modeline.
(spaceline-line-column-p t)
;; Use two colours to indicate whether a buffer is modified or not.
(spaceline-highlight-face-func 'spaceline-highlight-face-modified)
:config (custom-set-faces '(spaceline-unmodified ((t (:foreground "black" :background "gold")))))
(custom-set-faces '(spaceline-modified ((t (:foreground "black" :background "cyan")))))
(require 'spaceline-config)
(spaceline-helm-mode)
(spaceline-info-mode)
(spaceline-emacs-theme))
(spaceline-toggle-buffer-size-off) ;; Not interested in how large a buffer is.
(spaceline-toggle-input-method-off) ;; Usually a “Π” symbol in the modeline, since I use Unicode input with Agda, denoting the current language environment, buffer coding system, and current input method.
(spaceline-toggle-buffer-encoding-abbrev-off) ;; buffer-encoding-abbrev: the line ending convention used in the current buffer (unix, dos or mac).
(spaceline-toggle-hud-off) ;; A tiny “progress bar”; shows the currently visible part of the buffer.
(spaceline-toggle-helm-buffer-id-off) ;; I don't need to see “Helm M-x” whenever I press “M-x” or other Helm-powered commands.
#+end_src
Other separators ---of modeline information--- that I've considered include
~'brace~ instead of an arrow, and ~'contour, 'chamfer, 'wave, 'zigzag~ which look
like browser tabs that are curved, boxed, wavy, or in the style of driftwood.
:End:
*** Menu to Toggle Minor Modes: A quick way to see all of my modes, and which are enabled
:PROPERTIES:
:CUSTOM_ID: Menu-to-Toggle-Minor-Modes-A-quick-way-to-see-all-of-my-modes-and-which-are-enabled
:END:
Enabled minor modes clutter up the modeline with their names, albeit some have
useful status information shown. We can either selectively pick which
names/status are shown using diminish.el, possibly forgetting which minor modes
are enabled or we can use minions.el to “gather up” all enabled minor modes, and
recently enabled ones, under a single menu which doom-modeline shows as a simple
configurations gear icon. ⚙. :gear:
#+begin_src emacs-lisp
(use-package minions
:custom (doom-modeline-minor-modes t)
:hook (after-init . minions-mode))
#+end_src
*** Nice battery icon alongside with percentage, in doom-modeline
:PROPERTIES:
:CUSTOM_ID: Nice-battery-icon-alongside-with-percentage-in-doom-modeline
:END:
#+begin_src emacs-lisp :tangle init.el
;; If not for doom-modeline, we'd need to use fancy-battery-mode.el.
(display-battery-mode +1)
#+end_src
#+begin_details [Posterity / Disabled] Fancy Battery Setup
Let's have it also show remaining battery life, coloured green if charging and
coloured yellow otherwise. It is important to note that this package is no
longer maintained. It works on my machine.
#+BEGIN_SRC emacs-lisp :tangle no
;; Let's use a fancy indicator …
(use-package fancy-battery
:custom (fancy-battery-show-percentage t)
(battery-update-interval 15)
:config (fancy-battery-mode))
#+END_SRC
#+end_details
*** Time & date
:PROPERTIES:
:CUSTOM_ID: Time-date
:END:
Let’s display the current time, with updates every second.
#+begin_src emacs-lisp :tangle init.el
;; Show date and time as well.
;; [Simple Approach]
;; (setq display-time-day-and-date t)
;; (display-time)
;; [More Controlled Approach: Set date&time format]
;; a ≈ weekday; b ≈ month; d ≈ numeric day, R ≈ 24hr:minute.
(setq display-time-format "%a %b %d ╱ %r") ;; E.g.,: Fri Mar 04 ╱ 03:42:08 pm
(setq display-time-interval 1) ;; Please update the time every second.
(display-time-mode)
#+end_src
But doc:display-time-mode shows me a bit more info that I actually don't care
for; so let's disable those.
#+begin_src emacs-lisp :tangle init.el
;; I don't need the system load average in the modeline.
(setq display-time-default-load-average nil)
(setq display-time-load-average nil)
#+end_src
*** No Line, nor Column, Numbers ---and no buffer percentage
Likewise, let's have the modeline display column numbers, but not line numbers.
Instead, let's have line numbers on the side of the buffer; moreover let's have
a uniform width for displaying line numbers, rather than having the width grow
as necessary.
#+BEGIN_SRC emacs-lisp :tangle init.el
;; ;; Do not show me line numbers, nor column numbers, in the modeline
(column-number-mode -1)
(line-number-mode -1)
;; Likewise, no need to show me “Top∣Mid∣Bot” in the modeline.
(setq-default mode-line-percent-position nil)
#+END_SRC
Line numbers are a /conventionally expected/ part of a user interface, but I've
realised that I seldom /need to see/ them. I can still jump to a line number
provided by a compilation error with kbd:M-g_g; and toggle line numbers on when
I'm pair programming with doc:display-line-numbers-mode.
- In Emacs, there are /buffer/ which exist and contain textual data, but to
actually see them one requires a /window/. In the same vein, there are line
numbers but I don't need to always see them.
- If I need an indication of ‘progress’, the modeline contains a percentage of
how far I am in a buffer.
#+BEGIN_SRC emacs-lisp :tangle init.el
;; (setq display-line-numbers-width-start t)
;; (global-display-line-numbers-mode t)
#+END_SRC
*** Buffer names are necessarily injective :No_longer_needed_due_to_doom:Disabled:
:PROPERTIES:
:CUSTOM_ID: Buffer-names-are-necessarily-injective
:header-args: :tangle no
:END:
By default when multiple files sharing the same name are opened, say for
comparison from different directories, their buffers are named uniquely by
having the format “⟨file-name⟩ <𝓃>”, for numbers 𝓃. It'd be more helpful
to have the buffer names reflect their location.
#+BEGIN_SRC emacs-lisp
(use-package uniquify
:defer t
:ensure emacs
:custom ((uniquify-separator "/") ;; The separator in buffer names.
(uniquify-buffer-name-style 'forward))) ;; names/in/this/style
#+END_SRC
Note that this does not affect cloning buffers, kbd:C-x_4_c.
( A function /f/ is /injective/ precisely when it's /distinction-preserving/; i.e.,
/x ≠ y ≡ f x ≠ f y/. We can tell whether two things are the same or not, by
‘zooming in’ on their particular property ‘f’, which may be easier to compare.
E.g., object IDs, hashcodes, unique keys in database tables. )
( Why am I bringing this up? I like math and seldom get to use it; so why not! )
** Exquisite Fonts and Themes
:PROPERTIES:
:CUSTOM_ID: Exquisite-Fonts-and-Themes
:END:
Emacs' default theme leaves much to be desired: It does not look sleek and
shiny, which usually leaves first-timers with a poor, shallow, impression of the
system. Below we install a few themes that make Emacs look exquisite. We cycle
between the chosen themes with kbd:C-c_t, doc:my/toggle-theme.
#+begin_details “my/toggle-theme” Implementation
+ ~M-x load-theme RET TAB~ shows all themes, including built-in ones,
that may be loaded.
+ Loading multiple themes results in their pallets mixed.
- ~M-x disable-theme~ to remove a theme from the current pallet.
--------------------------------------------------------------------------------
#+begin_src emacs-lisp :tangle init.el
;; Treat all themes as safe; no query before use.
(setf custom-safe-themes t)
#+end_src
+ The [[https://github.com/hlissner/emacs-doom-themes/tree/screenshots][Doom Themes]] also look rather appealing.
+ A showcase of many themes can be found [[https://emacsthemes.com/][here]].
--------------------------------------------------------------------------------
#+BEGIN_SRC emacs-lisp :tangle init.el
;; Infinite list of my commonly used themes.
(setq my/themes
(cl-loop for (package . theme-variants-I-like) in
;; I like theme doom-flatwhite <3 It feels “warm”.
;; (I found out thanks to C-u C-c t!)
'((doom-themes doom-flatwhite doom-snazzy doom-monokai-ristretto doom-laserwave doom-solarized-light doom-vibrant)
(solarized-theme solarized-gruvbox-dark solarized-gruvbox-light)
(stimmung-themes stimmung-themes-light stimmung-themes-dark)
(shanty-themes shanty-themes-light)
(apropospriate-theme apropospriate-light) ;; /super/ nice! Super “clean”, like writing on paper
(tao-theme tao-yang) ;; nice light theme.
(leuven-theme leuven-dark leuven) ;; Nice minimal variant
(material-theme material-light)
(moe-theme moe-light)
(organic-green-theme organic-green)
(tango-plus-theme tango-plus)
;; I like all 3 variants.
(minimal-theme minimal minimal-black minimal-light)
(espresso-theme espresso)
(emacs dichromacy)
(nano-theme nano-light nano-dark)
(pink-bliss-uwu-theme pink-bliss-uwu)
(modus-themes modus-operandi-tinted))
do (package-install package)
append theme-variants-I-like))
(setcdr (last my/themes) my/themes)
#+END_SRC
kbd:C-c_t to toggle between the personal themes.
#+BEGIN_SRC emacs-lisp :tangle init.el
(cl-defun my/load-theme (&optional (new-theme (completing-read "Theme: " (custom-available-themes))))
"Disable all themes and load the given one ---read from user when called interactively."
(interactive)
(mapc #'disable-theme custom-enabled-themes)
(load-theme new-theme)
(message "Theme %s" new-theme))
(cl-defun my/toggle-theme (&optional (new-theme (pop my/themes)))
"Disable all themes and load NEW-THEME, which defaults from ‘my/themes’.
When a universal prefix is given, “C-u C-c t”, we load a random
theme from all possible themes. Nice way to learn about more
themes (•̀ᴗ•́)و"
(interactive)
(-let [theme (if current-prefix-arg
(nth (random (length (custom-available-themes)))
(custom-available-themes))
new-theme)]
(my/load-theme theme)))
(global-set-key "\C-c\ t" 'my/toggle-theme)
(unless noninteractive (my/toggle-theme))
(unless noninteractive (my/load-theme 'pink-bliss-uwu))
#+END_SRC
Apparently, there's already a package that accomplishes these goals and more:
[[https://github.com/myTerminal/theme-looper][theme-looper]]. I may switch to it, but for now my simple function above is
slightly informative, to me at least, about how themes work and it does what I
want.
...Actually, the above learning adventure has made it easy to provide a similar setup
for fonts 😁
#+end_details
Likewise, kbd:C-c_F, doc:my/toggle-font, to quickly change fonts (according to
mood 😸). [I already use kbd:C-c_f, doc:my/org-mode-format, for the more likely
operation of formatting text.]
#+begin_details “my/toggle-font” Implementation
#+begin_src emacs-lisp :tangle init.el
(when my/personal-machine?
;; Infinite list of my commonly used fonts
(setq my/fonts
'(;; NOPE: Breaks Gerrit! "Roboto Mono Light 14" ;; Sleek
"Input Mono 14"
"Source Code Pro Light 14" ;; thin, similar to Inconsolata Light
"Papyrus 14"
"Bradley Hand Light 12"
;; "Chalkduster 14" ;; Laggy!
"Courier Light 12"
"Noteworthy 9"
"Savoye LET 14"
"Fantasque Sans Mono 16"
))
(setcdr (last my/fonts) my/fonts)
;; Let's ensure they're on our system
;; brew search "/font-/" # List all fonts
(shell-command "brew tap homebrew/cask-fonts")
(system-packages-ensure "svn") ;; Required for the following font installs
;; No thanks! (system-packages-ensure "font-roboto-mono") ;; Makes Gerrit in Chrome look like Gibberish!
(system-packages-ensure "font-input")
(system-packages-ensure "font-source-code-pro")
(system-packages-ensure "font-fira-mono")
(system-packages-ensure "font-mononoki")
(system-packages-ensure "font-monoid")
(system-packages-ensure "font-menlo-for-powerline")
(system-packages-ensure "font-fantasque-sans-mono")
(system-packages-ensure "font-ibm-plex")
;; Use “M-x set-face-font RET default RET”, or...
;; (set-face-font 'default "Source Code Pro Light14")
;; See ~2232 fonts
;; (append (fontset-list) (x-list-fonts "*" nil))
(cl-defun my/toggle-font (&optional (new-font (pop my/fonts)))
"Load NEW-FONT, which defaults from ‘my/fonts’.
When a universal prefix is given, “C-u C-c F”, we load a random
font from all possible themes. Nice way to learn about more
fonts (•̀ᴗ•́)و"
(interactive)
(let* ((all-fonts (append (fontset-list) (x-list-fonts "*" nil)))
(font (if current-prefix-arg
(nth (random (length all-fonts)) all-fonts)
new-font)))
(set-face-font 'default font)
(message "Font: %s" font)))
(global-set-key "\C-c\ F" 'my/toggle-font)
;; Default font; the “ignore-⋯” is for users who may not have the font.
(ignore-errors (my/toggle-font "Fantasque Sans Mono 12"))
(ignore-errors (my/toggle-font "Source Code Pro Light 14"))
(ignore-errors (my/toggle-font "IBM Plex Mono 12")))
#+end_src
#+end_details
In any Org file, type ~elisp:menu-set-font~; then you can click on this link to
get a nice font selection menu ---this can be useful for your own ‘personal startup buffer’.
# Finally, for fun, let's colour all source blocks, in Org mode, by the background colour pink.
# (set-face-attribute 'org-block nil :background "pink")
# MA: This does not work well with dark themes; should use a theme-based setting.
Let's use the following theme and font, upon startup.
#+begin_src emacs-lisp :tangle init.el
(unless noninteractive
;; Breaks Gerrit: (my/toggle-font "Roboto Mono Light 14")
(my/toggle-theme 'solarized-gruvbox-light))
#+end_src
** Dimming Unused Windows
:PROPERTIES:
:CUSTOM_ID: Dimming-Unused-Windows
:END:
Let's dim windows, and even the whole Emacs frame, when not in use.
#+BEGIN_SRC emacs-lisp
(use-package dimmer
:hook after-init)
#+END_SRC
A more ‘fine-grained’ [[https://github.com/larstvei/Focus][tool]] dims all text except the ‘paragraph’ you're working
on. It's nifty, but not for me.
** TODO Flashing when something goes wrong
:PROPERTIES:
:CUSTOM_ID: Flashing-when-something-goes-wrong
:END:
Enable flashing mode-line on errors. E.g., ~C-g~, or calling an unbound key
sequence, or misspelling a word.
#+BEGIN_SRC emacs-lisp
;; (setq visible-bell 1) ;; On MacOS, this shows a caution symbol ^_^
;; The doom themes package comes with a function to make the mode line flash on error.
;; (use-package doom-themes)
;; (require 'doom-themes-ext-visual-bell)
;; (doom-themes-visual-bell-config)
#+END_SRC
--------------------------------------------------------------------------------
+A blinking cursor rushes me to type; let's slow down.+ Recently I'm thinking that
a blinking cursours prompts me to continue upwards and onwards.
#+BEGIN_SRC emacs-lisp
(blink-cursor-mode 1)
#+END_SRC
** Hiding Scrollbar, tool bar, and menu
:PROPERTIES:
:CUSTOM_ID: Hiding-Scrollbar-tool-bar-and-menu
:END:
As a laptop user, screen space is important, so let's remove rarely used visual
items.
#+BEGIN_SRC emacs-lisp :tangle init.el
(unless noninteractive
(tool-bar-mode -1) ;; No large icons please
(scroll-bar-mode -1)) ;; No visual indicator please
;; (menu-bar-mode -1) ;; The Mac OS top pane has menu options
#+END_SRC
** Highlight & complete parenthesis pair when cursor is near ;-)
:PROPERTIES:
:CUSTOM_ID: Highlight-complete-parenthesis-pair-when-cursor-is-near
:END:
Highlight matching ‘parenthesis’ when near one of them.
#+begin_src emacs-lisp :tangle init.el
(setq show-paren-delay 0)
(setq show-paren-style 'mixed)
(show-paren-mode)
#+end_src
Colour parens, and other delimiters, depending on their depth.
Very useful for parens heavy languages like Lisp.
#+begin_src emacs-lisp :tangle init.el
(use-package rainbow-delimiters
:hook prog-mode)
#+end_src
For example:
#+begin_src emacs-lisp :tangle no
(blue (purple (forest (green (yellow (blue))))))
#+end_src
There is a powerful package called ‘smartparens’ for working with pair-able
characters, but I've found it to be too much for my uses. Instead I'll utilise
the lightweight package ~electric~, which Emacs provides out of the box.
#+BEGIN_SRC emacs-lisp :tangle init.el
(electric-pair-mode 1)
#+END_SRC
It supports, by default, ACSII pairs ~{}, [], ()~ and Unicode ~‘’, “”, ⟪⟫, ⟨⟩~.
When writing Lisp, it is annoyong to have ‘<’ and ‘>’ be completed
/and/ considered as pairs. Let's disassociate them from both notions.
#+BEGIN_SRC emacs-lisp :tangle init.el
;; The ‘<’ and ‘>’ are not ‘parenthesis’, so give them no compleition.
(setq electric-pair-inhibit-predicate
(lambda (c)
(or (member c '(?< ?> ?~)) (electric-pair-default-inhibit c))))
;; Treat ‘<’ and ‘>’ as if they were words, instead of ‘parenthesis’.
(modify-syntax-entry ?< "w<")
(modify-syntax-entry ?> "w>")
#+END_SRC
:Rainbow_delims:
#+BEGIN_SRC emacs-lisp :tangle no
;; Act as usual unless a ‘<’ or ‘>’ is encountered.
;; ( char-at is really “character at poisition”; C-h o! )
(setq rainbow-delimiters-pick-face-function
(lambda (depth match loc)
(unless (member (char-after loc) '(?< ?>))
(rainbow-delimiters-default-pick-face depth match loc))))
#+END_SRC
:End:
*Adding Org-emphasise markers for pair completion ---Disabled.*
Let's add the org-emphasises markers: If we select a word then press =*=, it
becomes bold; likewise for ~/~ for emphasise.
#+BEGIN_SRC emacs-lisp :tangle no
(setq electric-pair-pairs
'((?~ . ?~)
(?* . ?*)
(?/ . ?/)))
;; Let's also, for example, avoid obtaining double ‘~’ and ‘/’ when searching for a file.
;; Disable pairs when entering minibuffer
(add-hook 'minibuffer-setup-hook (lambda () (electric-pair-mode 0)))
;; Renable pairs when existing minibuffer
(add-hook 'minibuffer-exit-hook (lambda () (electric-pair-mode 1)))
#+END_SRC
I use ‘~’ and ‘/’ too much during file navigation, and ‘*’ when marking numerous
Org headers, for which the ‘completed closing pair’ must tiresomely be deleted.
** Tabs :Disabled:
:PROPERTIES:
:CUSTOM_ID: Tabs
:header-args: :tangle no
:END:
I really like my Helm-supported ~C-x b~, but the visial appeal of a [[https://github.com/manateelazycat/awesome-tab][tab bar]] for Emacs
is interesting. Let's try it out and see how long this lasts ---it may be like Neotree:
Something cute to show to others, but not as fast as the keyboard.
#+BEGIN_SRC emacs-lisp :tangle no
(use-package awesome-tab
:quelpa (awesome-tab :fetcher git :url "https://github.com/manateelazycat/awesome-tab.git")
:config (awesome-tab-mode t))
;; Show me /all/ the tabs at once, in one group.
(defun awesome-tab-buffer-groups ()
(list (awesome-tab-get-group-name (current-buffer))))
#+END_SRC
It's been less than three days and I've found this utility to be unhelpful, to me anyhow.
An alternative is [[https://github.com/ema2159/centaur-tabs][centaur-tabs.]]
** Window resizing using the golden ratio :Disabled:
:PROPERTIES:
:CUSTOM_ID: Window-resizing-using-the-golden-ratio
:header-args: :tangle no
:END:
Let's load the following package, which automatically resizes windows so that
the window containing the cursor is the largest, according to the golden ratio.
Consequently, the window we're working with is nice and large yet the other windows
are still readable.
#+begin_src emacs-lisp :tangle no
(use-package golden-ratio
:init (golden-ratio-mode 1))
#+end_src
After some time this got a bit annoying and I'm no longer using this.
An alternative, also disabled:
#+begin_src emacs-lisp :tangle no
;; An automatic window-resizing mechanism.
;; A “calmer” alternative to golden-ratio.
;; https://github.com/cyrus-and/zoom
(use-package zoom :config (zoom-mode t))
#+end_src
** Replace phrases with nice SVG labels :Disabled:Causes_Org_rendering_issues:
:PROPERTIES:
:CUSTOM_ID: Replace-phrases-with-nice-SVG-labels
:header-args: :tangle no
:END:
:TODO_What_kind_of_Org_rendering_issues_are_caused:
Some org headings are not fontified, and Org links are not fontified; e.g.,
📆 [[https://calendar.google.com/calendar/u/0/r][Calendar]] ✉️
+ I have to copy-paste it to get it to fontify.
+ Likewise, Org headings need to be modified (e.g. pressing `t` to make them todo) to get them fontified.
:End:
[[ https://github.com/rougier/svg-tag-mode][SVG tags mode]] let's us replase arbitrary regular expressions with beautiful SVG
images that can be /clicked/ to produce an action, and may have a tooltip to
provide contextual information. Essentially an alternative to the built-in
doc:font-lock-mode, which performs arbitrary syntax highlighting.
- For more power, use the ~svg-lib~ package.
- The docs have nice examples. [[https://github.com/rougier/svg-tag-mode/blob/main/examples/example-2.el][Here]] are more useful examples.
# Below I setup a function, doc : my/svg-tag-declare-badge to /declaratively/ produce SVG badges.
#+begin_src emacs-lisp
(use-package svg-tag-mode
:hook (org-mode prog-mode)
;; :config (global-svg-tag-mode) ;; Nope: Breaks xwidget-webkit-browse-url, issue#28.
:config
(cl-defun my/svg-tag-declare-badge (template face &optional tooltip-message-upon-hover)
;; Example faces: 'org-level-1 'org-todo 'font-lock-doc-face
"Given a TEMPLATE of the shape \"𝑿❙𝒀\", make SVG badge whose tag is 𝑿 and label is 𝒀.
When `svg-tags-mode' is enabled, every occurence of \"\\(𝑿\\)\\(𝒀\\)\"
is replaced by an SVG image essentially displaying “[𝑿∣𝒀]” using the given FACE.
This badge can be clicked to show all instances in the buffer.
You can see the badges documentation / intentions / help-message when you hover over it;
to see TOOLTIP-MESSAGE-UPON-HOVER.
Both 𝑿 and 𝒀 are regeular expressions; “❙” serves as the SVG tag-label delimiter
---i.e., it saves as from writing \"\\(𝑿\\)\\(𝒀\\)\". Moreover, the SVG is only active
when regexp \"\\(𝑿\\)\\(𝒀\\)\" matches an instance."
;; Append tooltip message with a notice on what happens upon click.
(--> "Click on me to all see occurrences of this badge, in the current buffer!"
(if tooltip-message-upon-hover (concat tooltip-message-upon-hover "\n\n" it) it)
(setq tooltip-message-upon-hover it))
(-let [(tag label) (s-split "❙" template)]
(-let [click-to-show-all-buffer-occurrences `(lambda () (interactive) (occur (concat ,tag ,label)))]
;; Make an SVG for the tag.
(push
(cons (format "\\(%s\\)%s" tag label) `((lambda (tag) (svg-tag-make (s-chop-suffix ":" (s-chop-prefixes '("[" "<" "/*") tag)) :face (quote ,face) :inverse t :margin 0 :crop-right t :crop-left nil))
,click-to-show-all-buffer-occurrences
,tooltip-message-upon-hover))
svg-tag-tags)
;; Make an SVG for the label.
(push
(cons (format "%s\\(%s\\)" tag label) `((lambda (label) (svg-tag-make (s-chop-suffixes '("]" ">" "*/") label) :face (quote ,face) :crop-left t))
,click-to-show-all-buffer-occurrences
,tooltip-message-upon-hover))
svg-tag-tags))))
;; Let's start off empty; then declare badges below.
(setq svg-tag-tags nil)
;; Using caps so that these stick-out somewhat even when svg-tags-mode is not present.
(my/svg-tag-declare-badge "TODO:❙.*" 'org-todo "This is something I would like to do, in the future.")
(my/svg-tag-declare-badge "SILLY:❙.*" 'error "I’m experimenting; don't forget to clean-up when you’re done!")
(my/svg-tag-declare-badge "HACK:❙.*" 'error "This works, but it’s far from ideal. Plan to clean this in the future.")
(my/svg-tag-declare-badge "FIXME:❙.*" 'org-todo "This is busted! Plan to fix this in the future.")
(my/svg-tag-declare-badge "NOTE:❙.*" 'org-done "Something to be aware of; to keep in mind.")
;; [In]Active Time stamps --- M-x org-time-stamp
(my/svg-tag-declare-badge "\\[2022-.* ❙.*]" 'org-done "This is an inactive time stamp. It does not trigger the parent entry to appear in the agenda.")
(my/svg-tag-declare-badge "<2022-.* ❙.*>" 'org-todo "This is an active time stamp. It causes the parent Org entry to appear in the agenda.")
;; JavaScript Lint Rules: \* eslint (.*) */
(my/svg-tag-declare-badge "/\\* eslint ❙.* \\*/" 'org-done "It looks like you’ deviating from common conventions: Tread cautiously!")
;; TODO: Make SVG tags for other interesting “2-part” pieces of textual information
)
;; If everything is setup, the following examples should look like SVGs.
;; NOTE: Do something
;; TODO: fix me later
;; HACK: hiya
;; FIXME: this thing is busted 🎭
;; SILLY: start
;; SILLY: end
;; [2022-04-20 Sun 16:30]
;; <2022-04-20 Sun 16:30>
;; /* eslint eqeqeq: 0, curly: 2 */
;; NOTE: Toggle svg-tags-mode; useful when experimenting with new tags.
;; (progn (svg-tag-mode-off) (svg-tag-mode-on))
;; NOTE: (my/toggle-line-fontification) works fine with svg-tag-mode :-)
#+end_src
** Ibuffer: C-x C-b shows colour-coded buffers, grouped according to their git repos :Disabled:
:PROPERTIES:
:CUSTOM_ID: Ibuffer
:header-args: :tangle no
:END:
#+begin_src emacs-lisp :tangle no
;; Let's use an improved buffer list.
(use-package ibuffer ;; This is built-into Emacs.
:bind ("C-x C-b" . ibuffer))
;; It uses similar commands as does dired; e.g.,
;; / . org
;; This filters (“/”) the list with extensions (“.”) being “org”.
(use-package ibuffer-vc
:hook (ibuffer . (lambda ()
(ibuffer-vc-set-filter-groups-by-vc-root)
(unless (eq ibuffer-sorting-mode 'alphabetic)
(ibuffer-do-sort-by-alphabetic))))
:custom
(ibuffer-formats '((mark modified read-only " "
(name 18 18 :left :elide) " "
(size 9 -1 :right) " "
(mode 16 16 :left :elide) " "
(vc-status 16 16 :left) " "
(vc-relative-file)))))
#+end_src
+ [[http://martinowen.net/blog/2010/02/03/tips-for-emacs-ibuffer.html][Tips for using Emacs Ibuffer]]
+ (~10 minute video) [[https://cestlaz.github.io/posts/using-emacs-34-ibuffer-emmet/][Using Emacs - 34 - ibuffer and emmet - C'est la Z]]
+ (~10 minute video) [[https://www.youtube.com/watch?v=6KN_oSLFf-k&ab_channel=ProtesilaosStavrou][Emacs: introduction to IBUFFER - YouTube]]
** [better than ibuffer!] [[https://github.com/alphapapa/bufler.el][A butler for your buffers. Group buffers into workspaces with programmable rules, and easily switch to and manipulate them.]]
:PROPERTIES:
:CUSTOM_ID: https-github-com-alphapapa-bufler-el-A-butler-for-your-buffers-Group-buffers-into-workspaces-with-programmable-rules-and-easily-switch-to-and-manipulate-them
:END:
#+begin_src emacs-lisp
(use-package bufler
:bind* ("C-x C-b" . bufler-list))
;; I still prefer “C-x b” to be “helm-mini”, since when looking for a buffer it also shows me recently visited files.
#+end_src
** all-the-icons
:PROPERTIES:
:CUSTOM_ID: all-the-icons
:END:
#+begin_src emacs-lisp :tangle init.el
(use-package all-the-icons
;; Install fonts only if they're not already installed.
;; Source: https://github.com/domtronn/all-the-icons.el/issues/120#issuecomment-427172073
:config (let ((font-dest (cl-case window-system
(x (concat (or (getenv "XDG_DATA_HOME") ;; Default Linux install directories
(concat (getenv "HOME") "/.local/share"))
"/fonts/"))
(mac (concat (getenv "HOME") "/Library/Fonts/" ))
(ns (concat (getenv "HOME") "/Library/Fonts/" )))))
(unless (file-exists-p (concat font-dest "all-the-icons.ttf"))
(all-the-icons-install-fonts 'install-without-asking))))
#+end_src
** Having a workspace manager in Emacs :Disabled:
:PROPERTIES:
:CUSTOM_ID: Having-a-workspace-manager-in-Emacs
:header-args: :tangle no
:END:
I've loved using XMonad as a window tiling manager. I've enjoyed the ability to
segregate my tasks according to what ‘project’ I'm working on; such as research,
marking, Emacs play, etc. With [[https://github.com/nex3/perspective-el][perspective]], I can do the same thing :-)
That is, I can have a million buffers, but only those that belong to a workspace
will be visible when I'm switching between buffers, for example.
( The awesome-tab and centaur-tab, mentioned elsewhere here, can be used to
achieve the same thing by ‘grouping buffers together’. )
#+begin_src emacs-lisp :tangle no
(use-package perspective
:config ;; Activate it.
(persp-mode)
;; In the modeline, tell me which workspace I'm in.
(persp-turn-on-modestring))
#+END_SRC
All commands are prefixed by ~C-x x~; main commands:
+ ~s, n/→, p/←~ :: ‘S’elect a workspace to go to or create it, or go to ‘n’ext
one, or go to ‘p’revious one.
+ ~c~ :: Query a perspective to kill.
+ ~r~ :: Rename a perspective.
+ ~A~ :: Add buffer to current perspective & remove it from all others.
As always, since we've installed ~which-key~, it suffices to press ~C-x x~ then look
at the resulting menu 😃
** Kill all buffers that are not associated with a file :Disabled:
:PROPERTIES:
:CUSTOM_ID: Lisp-Helpers-Kill-all-buffers-that-are-not-associated-with-a-file
:header-args: :tangle no
:END:
#+begin_src emacs-lisp
(cl-defun my/clean-buffers ()
"Kill all buffers that are not associated with a file.
By convention, such files are named in *earmuffs* style."
(interactive)
(ignore-errors (mapcar #'kill-buffer (--filter (s-matches? "\\*.*\\*" it) (mapcar #'buffer-name (buffer-list))))))
#+end_src
** TODO [#A] COMMENT When I press ~C-x ←/→~ I'd like to ignore some silly buffers.
- If I want to see a particular buffer, I'll summon it explicitly.
+ E.g., Messages with ~C-h e~, Magit with ~C-x g~, Server Status with ~M-S-SPC~, etc.
#+begin_src emacs-lisp
(defun my/buffer-predicate (buffer)
"Run `C-u 0 C-x C-e' on the following form to see all buffer names and find the
ones annyoning you, then place those in the function body below
(mapcar #'buffer-name (buffer-list))
"
;; First let's kill a bunch of buffers
;; (my/clean-buffers) ;; TODO: Bad idea?
;; Next let's filter out any remaining ones [Redundant?]
(defvar my/ignore/buffer/name '("*Quail Completions*" "*Backtrace*" "*Help*" "*agda2*" "*sqls*" "*which-key*" "*Warnings*" "*Messages*" "Status of Services"))
(defvar my/ignore/buffer/prefix '("*helm" "*Helm" "*quelpa" "*lsp" "*Occur" "magit" "*Flymake" "*format" "*Shell" "*Async"
"*org-src-fontification:" "*Server:"))
(defvar my/ignore/buffer/suffix '("stderr*" "log*" "-ls*"))
(-let [name (buffer-name buffer)]
(not (or (member name my/ignore/buffer/name)
(--any? (s-starts-with? it name) my/ignore/buffer/prefix)
(--any? (s-ends-with? it name) my/ignore/buffer/suffix)))))
(set-frame-parameter nil 'buffer-predicate 'my/buffer-predicate)
#+end_src
Note: ~C-x C-r~ is very useful for jumping to recently visited files.
** Weather in the modeline
:PROPERTIES:
:CREATED: [2025-04-07 Mon 13:05]
:END:
#+begin_src emacs-lisp
(defcustom my/weather-refresh-interval 60
"Number of minutes between refreshes of weather information."
:type 'integer)
;; Use (cancel-timer my/weather--timer) to stop this.
(defvar my/weather-brief "")
(setq my/weather--timer
(run-with-timer (* 60 5) (* 60 my/weather-refresh-interval)
(defun my/weather-update ()
(interactive)
(setq my/weather-brief (shell-command-to-string "bash -c 'curl -s wttr.in/Niagara+Falls+Canada?format=%c%C+%t'"))
;; (setq my/weather-brief (shell-command-to-string "bash -c 'curl -s wttr.in/Toronto+Canada?format=%c%C+%t+and+windy:+%w'"))
(setq my/weather-full-details (shell-command-to-string "bash -c 'curl -s wttr.in/Niagara+Falls+Canada?T'"))
(force-mode-line-update))))
;;
(setq my/weather--indicator
`(:eval
(propertize (format " %s " my/weather-brief)
'face 'mode-line-buffer-id
'help-echo (concat ;; "Click to see full details"
(propertize "\n" 'face '(:height 0.4))
(propertize "[Click]" 'face `(bold (foreground-color . "green"))) " To see detailed weather report\n"
(propertize "[M-x my/weather-update]" 'face '(bold (foreground-color . "maroon"))) " To fetch latest weather data"
(propertize "\n " 'face '(:height 0.5)))
'local-map my/mode-line-weather-map
'mouse-face 'mode-line-highlight)))
;;
(add-to-list 'mode-line-misc-info my/weather--indicator)
;; (pop mode-line-misc-info) ;; To remove from the modeline.
(setq my/weather-posframe-visible nil)
(defvar my/mode-line-weather-map
(let ((map (make-sparse-keymap)))
(define-key map [mode-line mouse-1]
(lambda (_e)
(interactive "e")
(use-package posframe)
(if my/weather-posframe-visible
(posframe-delete "*my/weather-full-details-posframe-buffer*")
(posframe-show "*my/weather-full-details-posframe-buffer*"
:string my/weather-full-details
:position (point))
(message "Click on the weather modeline icon to close the posframe."))
(setq my/weather-posframe-visible (not my/weather-posframe-visible))))
map))
#+end_src
TODO: Besides modeline, have this info show up in the agenda :-)
Also, I have this in my ~/zshrc:
#+begin_src bash :tangle no
alias smile="emacsclient --eval '(dad-joke-get)' | cowsay | lolcat"
# Welcome message for new shells (also jump to emacs, maybe that's better than the shell)
date; smile
# See the weather when I open a terminal
# emacsclient --eval 'my/weather-brief' | lolcat # Alternatively, use cached value.
bash -c 'curl -s wttr.in/Niagara+Falls+Canada?format=%c%C+%t+and+windy:+%w\\n'
echo "~/.zhrc :: Hello, World!"
#+end_src
* Show me the diff!
:PROPERTIES:
:CREATED: [2025-09-30 Tue 11:58]
:END:
#+begin_src emacs-lisp
(defun my/show-string-diff (string1 string2)
"Show the difference between STRING1 and STRING2 using `diff` in Emacs."
(interactive "sEnter first string: \nsEnter second string: ")
(let ((temp-buffer1 (get-buffer-create "*Diff String 1*"))
(temp-buffer2 (get-buffer-create "*Diff String 2*")))
;; Fill the first buffer with string1
(with-current-buffer temp-buffer1
(erase-buffer)
(insert string1))
;; Fill the second buffer with string2
(with-current-buffer temp-buffer2
(erase-buffer)
(insert string2))
;; Call the diff command on the two buffers
(diff temp-buffer1 temp-buffer2)))
#+end_src
* ------------------------------------------------------------------------------------------------------------------------
* 🏃🏾 Engage with Agenda: Progressing tasks to completion via org-agenda & note taking
/What do I work on today?/
/What did I work on last week?/
Check my agenda (•̀ᴗ•́)و
#+begin_quote Org Manual
Due to the way Org works, TODO items, time-stamped items, and tagged headlines
can be scattered throughout a file or even a number of files. To get an
overview of open action items, or of events that are important for a particular
date, this information must be collected, sorted and displayed in an organized
way. Org can select items based on various criteria and display them in a
separate buffer.
#+end_quote
The time spent clarifying and organizing my tasks means that when it's time to engage with work, I
have /fewer choices/ to make and fewer reference materials to find. To decide what to do next, I can
see upcoming tasks with due dates, sort tasks by label, or create filters. (Filters are essentially
saved searches that sort your list with one click. They are also known as “org-agenda views”.)
Org agenda is about collecting and filtering information which may be scattered
among various org files. There are two competing implementations: The built-in
~org-agenda~ module and the external ~org-ql~ module. The former is feature-rich
but its query syntax is difficult to get right and it lacks a “on-the-fly
show-me-results-as-I-type” interface; in-contrast ~org-ql~ provides these
features (and more) but lacks the mature configurability of the built-in module.
Moreover, ~org-ql~ has a different design than ~org-agenda~, as such the idea of
“agenda blocks” is present to help users migrate between the two and not a high
priorty of ~org-ql~. Anyhow, getting queries right is more important (and
configurations can always be done with some Lisp Advice), so I'm using ~org-ql~.
The Org Mode agenda is a special kind of buffer that aggregates headings and
TODO items from your Org Mode files to make it much easier to see and act on
them all.
** Why Emacs? Because of Org-agenda: /“Write fragmentarily, read collectively”/
Emacs is a powerful note-taking tool, supporting todo-lists, schedule management, code execution and
much more. Emacs allows you to “write fragmentarily, read collectively”: You can write your notes
anywhere, then its org-agenda (or howm) search features let you filter by date, by tag, by priority,
by property, or even by searching notes for arbitrary text. The resulting collection can be exported
into its own file, it can be sorted, or you can act on any entry in the resulting collection, such
as by scheduling it, adding properties, or clocking-into them. For example, one can produce such a
report of upcoming appointments and deadlines for the next month relating to a specific tag.
For instance,
+ *Automatic Date Search.* Any timestamp can be clicked, thereby opening the agenda for that date.
You can then see what you did that day, or what is upcoming on that day.
+ *Automatic Keyword Search.* Tags can be used to categorize notes. A note may be marked with many
keywords and thus related to many topics. If you move your cursor to a keyword ~:tag:~, and hit
~RETURN~, a keyword search is performed. This shows all entries that have the same tag. So by
creating a keyword, you also create links wherever the keyword occurs. You can also type the
command ~M-x org-agenda m~ to initiate a keyword search at any time, anywhere.
- Note: Tags are generally not in “kebab-case” since Agenda use “-” as the negation operator.
# - I use tags mostly for filtering in the agenda. This means you can find tasks with a specific tag
# easily across your large number of org-mode files.
| /Org Agenda is a fancy search for the files that contain your tasks and notes./ |
Unlike ~grep~, Agenda is date-aware, todo-aware, tag-aware, property-aware, etc. It is “workflow
aware”; E.g., it knows about:
| TODO, …, DONE | Tasks that you'd like to eventually do (or have started, ⋯, or are done) |
| ~DEADLINE:~ | Tasks that need to be done by a specific date |
| ~SCHEDULED:~ | Tasks that you won't (or can't) start until a specific date |
| ~STYLE: habit~ | Tasks that you should do with some frequency |
| ~EFFORT: 2:00~ | Tasks that you think will require 2hours to complete |
| ~LOW, MID, HIGH~ | Tasks that you think should of as “LOW, MID, HIGH” priority |
| ~𝒫: 𝒱~ | Tasks that have (meta-data) property 𝒫 with value 𝒱. |
For instance, you can use org-agenda to see all of your non-habit tasks ordered by deadline /then/
ordered by priority /then/ ordered by TODO-status (e.g., =TODO, STARTED, DONE=) /then/ ordered by their
effort. With such a view, at the end of the day, you can then schedule the top 3 tasks for the next
day; knowing that the top of the list contains the most important /and/ most urgent tasks.
*In-particular, the agenda relieves you from having to manually maintain such a list of prioritised
tasks.* Moreover, the view is /completely interactive/: You can modify tags, todo-states, (re)schedule,
etc directly from the view itself.
/The agenda is my personal dashboard; just as my Org inbox is my personal inbox!/
+ Org Inbox ≈ Email + Slack + Code Review Requests + ⋯
+ Org Agenda ≈ Jira dashboard + Gerrit dashboard + Company dashboard + ⋯
#+begin_src emacs-lisp
;; I like to write everything in one massive file, and the agenda should consult it.
(setq org-agenda-files (list "~/Dropbox/my-life.org"))
#+end_src
| 🥰 I am using ~org-ql~ to generate my agenda: It is more expressive /and/ more performant than the built-in ~org-agenda~. |
#+begin_src emacs-lisp
;; `org-ql' is a Lispy query language for Org files. It allows you to find Org
;; entries matching certain criteria and return a list of them or perform
;; actions on them.
(use-package org-ql :defer t)
#+end_src
*Org-agenda is known as “filters” in other apps.* As your life gets filled up
with tasks, finding information needs to be quick and efficient. That's where
filters come in handy! *Filters* are custom views for your tasks based on
specific criteria. It can be a task name, due date, project, label, priority,
date created, and more.
Here's a few handy filters / agenda reports to try out:
#+begin_src org :tangle no
+ [[org-ql-search:t][📚 All headlines]]
+ [[org-ql-search:(or (todo) (done))][📌 All tasks]]
+ [[org-ql-search:(and (todo "STARTED") (priority "A"))][🚲 All STARTED high-priority tasks]]
+ [[org-ql-search:(not (deadline))][❌ Headlines with no due date]]
+ [[org-ql-search:(and (deadline :from 0 :to 15) (not (deadline :with-time t)))][🕒 Tasks with due date, in 15 days, but no time]]
+ [[org-ql-search:(and (todo "WAITING") (deadline :from today :to +7))][⌚ WAITING due in 7 days]]
+ [[org-ql-search:(and (property "CREATED") (ts :from -30))][✏️ Created over 30 days ago]]
+ [[org-ql-search:(property "ASSIGNED_BY" "me")][🫵 Assigned by me]]
+ [[org-ql-search:(property "ASSIGNED_TO" "Becky")][👧 Assigned to Becky]]
+ [[org-ql-search:(and (property "PROJECT" "khums") (not (property "ASSIGNED_TO")))][💼 🤷 Unassigned tasks for Project Khums]]
+ [[elisp:(org-ql-search (current-buffer) `(and (deadline :from 0 :to ,(format-time-string "%Y-%m-%d %a %H:%M" (org-read-date nil t "+2h")))))][🕗 Due in next 2 hours, not overdue]]
+ [[org-ql-search:(and (tags "Work") (not (scheduled)) (not (deadline)))][🚫 Unscheduled Work tasks]]
+ [[org-ql-search:(and (priority <= "B") (deadline :from 0 :to 14)))][🔥 High-priority in 2 weeks]]
+ [[org-ql-search:(and (todo) (regexp "SCHEDULED: <.*Sat.*>"))][⛱️ Saturday tasks]]
+ [[org-ql-search:(tags "Email")][📧 Email related tasks --so you can complete them all at once and minimize the time you spend in your email]]
+ [[org-ql-search:Meeting][🤼 All entries that mention “Meeting” anywhere in the entry]]
+ [[org-ql-search:(and "Meeting" (not "Marketing"))][🤼-🗞️ All entries that mention “Meeting” anywhere but not “Marketing” anywhere in the entry]]
- OR: “ M-x helm-org-ql Meeting !Marketing ”, to see results as you type!
+ [[org-ql-search:(parent "Work Project")][💼 All sub-items in my Work Project]]
+ [[org-ql-search:(and (parent "Work Project") (not (tags)))][🎟️ All untagged subitems in my Work Project]]
+ [[org-ql-search:(and (priority "A") (not (scheduled)) (not (deadline)))][🔥 Urgent /yet/ unscheduled tasks!]]
#+end_src
Notice that they're in Org link syntax: /They're clickable queries!/
Filters can be based on
+ Keywords :: E.g., /See all tasks that contain the word "Meeting" that are due today/
+ Due dates :: /See all tasks due on January 3rd./
+ Priority :: /See all HIGH-priority tasks./
+ Tags :: /See all ~:garden:~ tasks/.
+ Projects :: Restrict org-agenda to a dedicated project; e.g., see all tasks
for a certain project.
+ Creation :: /See all tasks created within the last 30 days/.
Another example is ~(org-ql-search (org-agenda-files) '() :sort '(todo
priority))~. This shows me all of my (possibly non-task) headlines sorted by
todo state then sorted by priority. The main benefit here is I can keep
/active/ tasks under their own disjoint ‘projects’, yet still have a nice
unified view of all of my /active/ *and* non-active tasks.
+ ⇒ Much nicer than me physically collecting /and/ sorting tasks! ⇐
An important distinction: The first two clickable queries above are subtely
different. The first is all headlines, the second is all tasks. So when should
a headline have a TODO state? /If I need a reminder to do something, then it's
a task. That is, tasks track progress on actions that I want to do./
** [#C] COMMENT Example Agenda Report
:PROPERTIES:
:CREATED: [2025-04-12 Sat 16:26]
:END:
A notable problem I personally have is that I start tasks but then move on to other tasks, thereby
essentially rendering my previous efforts “as a waste of time” since the efforts didn't lead to a
finished task. I can avoid this by having my daily agenda /also/ show me all started tasks: That way,
perchance, I actually decide to do some (or at least one!) of the started tasks today.
#+begin_src emacs-lisp :tangle no
(setq org-agenda-custom-commands
'(("a" "Daily Agenda View, followed by Started Tasks"
((agenda "" ((org-agenda-span 'day) (org-agenda-overriding-header "Please focus on 𝒪𝓃𝓁𝓎 these tasks for the day!")))
(tags "-Someday+todo=\"STARTED\""
((org-agenda-overriding-header "Please 𝒓𝒆𝒅𝒖𝒄𝒆 the number of (unscheduled) open loops")
(org-agenda-skip-function '(org-agenda-skip-entry-if 'scheduled))))))))
#+end_src
(Note: I like this so much, that I used ~a~ as the key thereby overriding the default ~agenda~-only
view.)
Note: I'm asking for all ~STARTED~ tasks that are /not/ tagged as ~:Someday:~ since I have so many started
tasks that I use my Weekly Review to /remove/ the ~:Someday:~ tag from them if I'd like to start seeing
them in my daily agenda view.
Finally, the third argument to the ~tags~ type is a ~let~-style configuration list that applies /only/ to
that part of the resulting view. In this case, I've set the header to an informative title /and/ I
skip all entries that are already scheduled. These are the usual variables that you can set globally
for your agenda, such as ~org-agenda-span~ but they apply locally (in a ~let~-style) to a specific
agenda view.
See the [[https://orgmode.org/manual/Matching-tags-and-properties.html][official docs]] on how to write these kinds of queries.
When the agenda view appears, you can further filter the list, say by using a regular
expression. For example, pressing ~/~ beings the filter prompt, then enter ~-/marcus/~ will remove all
entries mentioning ~marcus~.
A view is ephemeral. If you'd like to share a view with others, you can invoke ~org-agenda-write~ to
obtain an Org file with the /full contents/ of the entries of the view. The official docs mention an
even faster approach if you export views often; e.g., as an HTML file with predefined name.
** Timestamps and their uses
Each row includes all features of the rows before it.
| Inactive timestamp | =C-c != | A date that I can click and it opens my agenda to that date |
| Plain timestamp | =C-c .= | Show me the task on my agenda /only/ on this date; e.g., a holiday |
| Scheduled timestamp | =C-c C-s= | Show me the task on its date, and keep showing it until I finish it |
| Deadline timestamp | =C-c C-d= | Show me the task /ahead/ of this /due date/ so that I can prepare for it |
For instance, I have the following task. I do not need to mark this as “done”: Either I attended the
barbecue or not. The important thing is that this task appears on my agenda on Saturdays. If you run
~(setq org-agenda-files (list "the/path/to/this/file.org"))~, then click on the date, then press =v m=
you'll see the Saturday repetitions every week.
#+begin_src org :tangle nil
,** Family BBQ <2024-08-10 Sat 15:00 ++1w> :Recurring:Personal:Outdoors:
Enjoy time with my family and friends.
#+end_src
*The fundamental feature of timestamps is that we can click them to get the agenda on that day, to
see all tasks that have (anywhere) an _active_ timestamp for that day.* For example, in Org mode, click
on <2025-08-16 Sat> to see an agenda view specifically for that day. We can also package this into a
method:
#+begin_src emacs-lisp
(defun my/agenda-for-day ()
"Call this method, then enter say “-fri” to see tasks timestamped for last Friday."
(interactive)
(let* ((date (org-read-date))
(org-agenda-buffer-tmp-name (format "*Org Agenda(a:%s)*" date))
(org-agenda-sticky nil)
(org-agenda-span 'day)
;; Putting the agenda in log mode, allows to see the tasks marked as DONE
;; at the corresponding time of closing. If, like me, you clock all your
;; working time, the task will appear also every time it was worked on.
;; This is great to get a sens of what was accomplished.
(org-agenda-start-with-log-mode t))
(org-agenda-list nil date nil)))
#+end_src
Further Reading:
+ [[https://endlessparentheses.com/better-time-stamps-in-org-export.html][Better time-stamps in org-export: Removing the “<⋯>” delimiters on export]]
** My default ~org-agenda-custom-commands~
:PROPERTIES:
:CREATED: [2025-04-12 Sat 19:03]
:END:
#+begin_src emacs-lisp
;; For each block in my Agenda, only show appointments, and tasks, occurring
;; today. For this week, month, etc, press “v w” or “v m”.
(setq org-agenda-span 'day)
(setq org-agenda-sticky nil)
#+end_src
#+begin_src emacs-lisp
(setq org-agenda-custom-commands
'(("t" "My list of all TODO entries" tags-todo "-recurring-someday+LEVEL=3"
((org-agenda-overriding-header "\nTODOs sorted by state, priority, effort")
(org-agenda-sorting-strategy '(todo-state-down priority-down effort-up))
(org-super-agenda-groups (progn
(org-super-agenda-mode t)
'((:name "Important" :and (:priority "A" :not (:todo ("DONE" "CANCELLED"))))
(:name "Process your Inbox" :tag "inbox")
(:name "Approved" :todo "APPROVED")
(:name "Started" :todo "STARTED")
(:name "Waiting" :todo "WAITING")
(:name "Low Priority" :priority "C" :tag "maybe"))))))
("a" "Daily Agenda; Productivity ≈ ♯DONE / ♯TASKS"
(
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
;; New things coming into my life ;;
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
(org-ql-block
'(tags "inbox")
((org-ql-block-header "\n📩 Process Inbox: “m” to mark then “B r” to refile marked items 📥\n")))
;; MA: Moved this to Weekly Review. ;;
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
;; High priority 𝒚𝒆𝒕 unscheduled tasks ;;
;; ;;
;; Note to self: When I write this query, I thought “I doubt I have ;;
;; any hits, this is too silly”. I was wrong. I had 300+ hits. ;;
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
;; (org-ql-block
;; '(and (priority "A") (not (scheduled)) (not (deadline)))
;; ((org-ql-block-header "\n🔥 High priority 𝒚𝒆𝒕 unscheduled tasks 🚒\n")))
;; MA: Moved this to Weekly Review. ;;
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
;; Items to review: Mine for useful info then archieve or delete ;;
;; ;;
;; `M-x org-copy` is your friend. Archive an entry as is, but copy the ;;
;; useful parts. Archiving is useful for clocking reports from the ;;
;; past. ;;
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
;; (org-ql-block
;; `(and (done) (not (tags "Top")) (closed :to ,(- (calendar-day-of-week (calendar-current-date))))) ;; i.e.; :to ,(org-read-date nil nil "-1d")
;; ((org-ql-block-header (propertize "\n📜 Items to review: Mine for useful info then archieve or delete. ☑️\n"
;; 'help-echo "Press E to toggle seeing ~5 lines of each entry."
;; ;; Reduce the number of DONE and archived headlines so agenda operations that skip over these can finish faster.
;; ))))
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
;; Items explicitly marked as the top focus goals for the month ;;
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
(org-ql-block
'(tags-local "Top")
((org-ql-block-header "\n⚡ Top goals for the month ⚡\n")
(org-agenda-remove-tags t)))
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
;; Tasks that would bring me joy ;;
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
(org-ql-block
'(and (tags-local "Happy") (or (scheduled -7) (deadline -7) (not (done))))
((org-ql-block-header "\n🤗 I'd be happy if I got the following done this week 🥰\n")
(org-agenda-remove-tags t)))
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
;; What “I've done so far” is all tasks closed this week. ;;
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
;; Note the definition of “done” includes all terminal states in my workflow.
(org-ql-block
`(and (not (tags "Recurring")) (done) (closed :from ,(- (calendar-day-of-week (calendar-current-date))) :to today)) ;; “start-of-week” /from today/
((org-ql-block-header (propertize "\n✅ What I've done so far this week 💯\n" 'help-echo "Press E to toggle seeing ~5 lines of each entry. \n If DONE, mine for useful info then archive or delete."))))
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
;; Deadlines: Upcoming tasks I should prepare for ;;
;; ;;
;; NOTE: I don't want to use predicate (not (done)) since I want to ;;
;; see the DONE items as a reminder to myself to actually archive ;;
;; these tasks. ;;
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
(org-ql-block
'(and (deadline auto) (not (tags "Top")) (not (done)))
((org-ql-block-header "\n🎯 Deadlines\n")))
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
;; Whoops, things that I've missed! ;;
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
(org-ql-block
'(and (not (habit)) (not (tags "Top")) (not (done)) (scheduled :to today) (not (scheduled :on today)))
((org-ql-block-header "\n📆 Overdue\n")))
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
;; Things loads into my cognitive memory that I should probably continue? ;;
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
(org-ql-block
'(and
(todo "STARTED")
(level '> 1)
(not (tags-local "Someday" "Top" "SocialCredit"))
(not (scheduled :from today)))
((org-ql-block-header "\n🤡 Please 𝒓𝒆𝒅𝒖𝒄𝒆 the number of (unscheduled) open loops\n")))
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
;; Stuff I'd like to do today; but do I actually have the time to do so? ;;
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
(org-ql-block
'(and (scheduled :on today) (ts :with-time nil))
((org-ql-block-header "\n😵💫 ﴾ Any time ≈ No time﴿ Scheduled today, but not time-blocked\n")))
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
;; What am I doing today, and when? ;;
;; ;;
;; TODO: Use “agenda*” ? The agenda* view is the same as agenda ;;
;; except that it only considers appointments, i.e., scheduled and ;;
;; deadline items that have a time specification ‘[h]h:mm’ in their ;;
;; timestamps. ;;
;; https://orgmode.org/manual/Special-Agenda-Views.html#FOOT172 ;;
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
(agenda ""
((org-agenda-overriding-header
"\n🔎 Please focus on 𝒪𝓃𝓁𝓎 these tasks for the day!")
(org-agenda-format-date "")
(org-agenda-skip-function
(lambda nil (org-back-to-heading t)
(cl-letf*
(((symbol-function 'day)
(lambda (org-date-string)
(cl-fourth (org-parse-time-string org-date-string))))
((symbol-function 'month)
(lambda (org-date-string)
(cl-fifth (org-parse-time-string org-date-string))))
((symbol-function 'is-repeating)
(lambda (org-date-string)
(s-matches? "<[^ ]* [^ ]* [^ ]* [^ ]*\\(d\\|m\\)>"
org-date-string)))
((symbol-function 'before)
(lambda (x y)
(or (< (month x) (month y))
(and (= (month x) (month y)) (<= (day x) (day y))))))
((symbol-function 'at-least)
(lambda (x y) (or (equal y x) (before y x))))
((symbol-function 'skip)
(lambda nil (save-excursion (org-end-of-subtree t) (point))))
(scheduled (org-entry-get (point) "SCHEDULED"))
(today (org-read-date nil nil "+0d"))
(non-habit?
(not
(equal "habit"
(ignore-errors
(downcase (org-entry-get (point) "STYLE"))))))
(deadline? (org-entry-get (point) "DEADLINE"))
(overdue? (not (or (not scheduled) (at-least scheduled today))))
(scheduled-without-time
(and scheduled (not (s-matches? "<.* .* .*:.*>" scheduled)))))
(when
(and non-habit?
(or deadline? overdue? scheduled-without-time
(and scheduled
(or (s-matches? "<[^ ]* [^ ]*>" scheduled)
(s-matches? "<[^ ]* [^ ]* [^ ]*\\(d\\|m\\)>"
scheduled)))))
(skip)))))
(org-agenda-current-time-string (s-join "\n\t\t\t\t" (-repeat 3 "⏰⟵⏰⟵⏰⟵⏰⟵⏰⟵⏰⟵⏰⟵⟨ 𝒩ℴ𝓌 ⟩⟶⏰⟶⏰⟶⏰⟶⏰⟶⏰⟶⏰⟶⏰")))
;; :org-agenda-remove-tags t
;; :org-agenda-time-grid nil
;; :org-use-tag-inheritance nil
(org-agenda-span 'day)
;; I want work items to automatically have a briefcase next to them.
(org-agenda-prefix-format " ○ %t % i%s") ;; The “%i” is the icon on the next line.
(org-agenda-category-icon-alist '(("\\`work\\'" ("💼") nil nil :ascent center)))
(org-agenda-time-grid
'((daily today require-timed) (800 1000 1200 1400 1600 1800 2000) "" ""))))
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
;; A glimpse into later this week. ;;
;; ;;
;; What I've left to do is all incomplete tasks scheduled within the ;;
;; next 5-𝓃 days, where 𝓃 is the numeral of the current week day. ;;
;; Mon=1, ⋯, Thu=4, ⋯ ;;
;; ;;
;; NOTE: org-ql and org-agenda are two implementations of essentially ;;
;; the same idea. As such, org-ql doesn't honour all of org-agenda's ;;
;; configurations. E.g., org-agenda-sorting-strategy seems to be ;;
;; honoured when set to todo-state-up, but otherwise ignored. See ;;
;; https://github.com/alphapapa/org-ql/issues/79, “Sort entries by due ;;
;; date when using org-ql-block #79”. See also ;;
;; https://github.com/alphapapa/org-ql/issues/370, “Agenda entries are ;;
;; missing properties necessary for view filtering #370”. ;;
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
(org-ql-block
(cl-letf (((symbol-function 'org-ql-view--add-todo-face) (lambda (ignored_todo_state))))
`(and (not (tags "Recurring" "Happy")) (not (done)) (scheduled :from 1 :to ,(- 7 (calendar-day-of-week (calendar-current-date)))))) ;; “end-of-week” /from today/
((org-agenda-sorting-strategy '(timestamp-up)) ;; Sort by any timestamp, early first. ;; ⟵- Not yet honoured, see #79.
(org-agenda-todo-keyword-format "") ;; ⟵- Not yet honoured, see #79.
(org-ql-block-header (propertize
"\n🗯️ Incomplete tasks scheduled later this week\n"
'help-echo "Be aware!"))))
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
;; Stuff I'm waiting on others to repond to. ;;
;; ;;
;; TODO: When I enter the WAITING state, add a property WAITING_SINCE ;;
;; with a timestamp. Then this query here can inspect that timestamp ;;
;; and see if it's been over a week. ;;
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
(org-ql-block
'(todo "WAITING")
((org-ql-block-header "\n💢 I've been waiting on these [for over a week?], send reminder!\n")))
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
;; Add more items here ;;
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
))))
;; NOTE: I find these queries by playing with: (org-ql-search org-agenda-files '(tags-local "Top"))
;; All entries with a timestamp that looks like “<2025-04-16 Wed 18:00-18:30 .+1w>”, the important part is “.+”.
;; (org-ql-search org-agenda-files '(and (ts) (regexp "<[[:digit:]]\\{4\\}-[[:digit:]]+-[[:digit:]]+ .*\\.\\+.*>")) :title "All of my recurring events")
;; From: https://orgmode.org/manual/Speeding-Up-Your-Agendas.html
(setq org-agenda-ignore-properties '(stats)) ;; This will disable parsing and updating statistic cookies.
;; org-ql-block is mostly a "nice to have" feature. It isn't a high priority to
;; make it 100% compatible with every Org Agenda feature (doing so would
;; practically go against the purpose of org-ql, which began as a
;; reimplementation). [Src:
;; https://github.com/alphapapa/org-ql/issues/79#issuecomment-2360241077]
;;
;;
(setq my/special-org-ql-header "\n🗯️ Incomplete tasks scheduled later this week\n")
;; Hide TODO keyword
(advice-add
'org-ql-view--add-todo-face
:around
(defun my/org-ql-omit-todo-keyword-for-specific-header-block (orig-fn keyword)
(unless (string-equal org-ql-block-header my/special-org-ql-header)
(funcall orig-fn keyword))))
;; Hide PRIORITY
(advice-add
'org-ql-view--add-priority-face
:around
(defun my/org-ql-omit-priority-for-specific-header-block (orig-fn keyword)
(unless (string-equal org-ql-block-header my/special-org-ql-header)
(funcall orig-fn keyword))))
;; My default sorting strategy
;; Sort by DATE, for any org-ql-block-header
(advice-add
'org-ql-select :around
(defun my/org-ql-select--sort-if-needed (orig-fn from query &rest args)
"Advice around `org-ql-select` to inject :sort '(date) under special block headers."
(apply orig-fn from query
(if (and org-ql-block-header
(not (equal org-agenda-type 'agenda))
(not (equal org-agenda-overriding-header "\n🔎 Please focus on 𝒪𝓃𝓁𝓎 these tasks for the day!")))
(apply #'plist-put args :sort '(date))
args))))
#+end_src
/Say no to more work :) Looking at your solid-packed agenda for the next day works wonders for saying no./
Aside: Why are all of my block headers padded with extra new lines? I want them
to be "independent" of the seperator lines (which I want to keep), so that when
I TAB on a heading, it fold the entire block /and/ leaves the header title
visible so I can TAB to unfold.
#+begin_src emacs-lisp
;; ≡ Enable folding via indentation in normal agenda buffer ≡
;; So that I can easily “TAB” to toggle folding sections 😉
(use-package origami
:bind (:map org-agenda-mode-map ("" . origami-toggle-node))
:hook org-agenda-mode)
;;
;; Alternatives: my/auto-set-selective-display-mode or (set-selective-display 1)
#+end_src
Goal: I'm focusing on keeping my agenda view from getting too lengthy.
** Getting Started with org-agenda
The three main functions used to create Agenda buffers are doc:org-agenda-list, doc:org-tags-view, and
doc:org-search-view. I've placed my preset agenda views on speed-dial with a shortcut: ~C-c a~.
The next day I begin my work, I press kbd:C-c_a to see the scheduled tasks
for the day ---kbd:C-c_C-s to re-schedule the task under the cursor and [[kbd:r]]
to refresh the agenda.
#+begin_src emacs-lisp
;; Jump straight to my 𝓪genda dashboard ---no dispatch menu please!
(bind-key
"C-c a"
(defun my/org-agenda ()
(interactive)
(org-agenda nil "a")
(when org-super-agenda-mode
(org-super-agenda-mode -1)
(org-agenda-redo))
(beginning-of-buffer)))
;; I want the following to happen whenever I do “g” or “/” in the agenda.
(add-hook 'org-agenda-finalize-hook
(defun my/agenda-look-nice ()
(-let [fill-column 120]
(perfect-margin-mode))
(message "Press “/ -Work” to hide all :Work: entries.")))
;; Reduce unhelpful visual clutter.
;;
;; Everything in my agenda is something I need to do, so no need to show me the actual todo state.
;; The TODO state is useful for filters, but after the filter it's not useful to see.
;; (To hide priorities as well, maybe not advisble, see https://emacs.stackexchange.com/a/61451)
(setq org-agenda-todo-keyword-format "")
#+end_src
** Agenda Dashboard: Buttons & Random Quote
:PROPERTIES:
:CREATED: [2024-07-18 Thu 14:25]
:END:
#+begin_src emacs-lisp
;; For testing:
;; (aql "hola" :query [(= TODO "I don't care, just show me the dashboard please")] :interactive t)
;;
(cl-defun my/insert-button (label action &key (foreground "white") (background "blue") (echo "This is a custom button"))
"Insert a styled button at point"
;; Example Use:
;; (my/insert-button "Hello" (lambda (pos) (message (format "Hello at %s" pos))) :foreground "cyan" :background nil :echo "Press me!!")
(interactive)
;; TODO: Use lf-define instead
(cl-assert (stringp label) t "my/agenda-button: First arg should be a string")
(cl-assert (functionp action) t "my/agenda-button: Second arg should be a lambda")
(let ((start (point)))
(insert-text-button
label
'action action
'follow-link t
:type (define-button-type 'custom-button
;; https://www.gnu.org/software/emacs/manual/html_node/elisp/Face-Attributes.html
'face (list :foreground foreground
:background background
:slant 'italic
:weight 'bold
:box '(:line-width 2 :style released-button))
'help-echo echo))))
(add-to-list
'org-agenda-finalize-hook
(cl-defun my/extra-agenda-prose ()
(goto-char 1) ;; Sometimes this is not honoured by org-agenda, e.g., when changing state of a task
(when (= (point) 1) ;; i.e., only do this once, when the buffer was created.
(my/insert-button "New Journal Entry"
(lambda (pos) (my/capture-journal-entry))
:foreground "cyan"
:background nil
:echo "I enjoy rereading my journal and reliving nice memories ᕦ( ᴼ ڡ ᴼ )ᕤ")
;; TODO:? “See all `:Work:` open loops” button?
(insert "\t")
(my/insert-button "Consume Content"
(lambda (pos) (my/consume-content))
:foreground "cyan" :background nil
:echo "Get a random subtree from “Consume Content”")
(insert "\t")
(my/insert-button "Tell me a funny!"
(lambda (pos) (message (dad-joke-get)))
:foreground "cyan"
:background nil
:echo "Smile, it's a form of charity!")
(insert "\t")
(my/insert-button "Random WikiShia"
(lambda (pos) (browse-url "https://en.wikishia.net/view/Special:Random"))
:foreground "cyan"
:background nil
:echo "Learn, grow!")
(insert "\t")
(my/insert-button "Search" ;; TODO: As I learn more agenda search features, I'll make this into a completing-read menu?
(lambda (pos) (org-agenda nil "t"))
:foreground "pink"
:background nil
:echo "All TODOs I'd like to actually work on, so as to have a meaningful life")
;;
;; NOTE: ‘someday’ things sometimes go into my quote system so that I run into them sometime; lol likewise for things I want to remember
;;
(insert "\n")
(setq my/quote-start (point))
(setq my/quote-end nil)
(insert-text-button
" " ;; Populated via “ display ”; but must be non-empty.
'action (lambda (&rest args)
(read-only-mode -1)
(put-text-property my/quote-start my/quote-end 'display (my/string-fill-column-and-center 70 (my/random-quote)))
(read-only-mode +1))
'display (format "\n%s\n" (my/string-fill-column-and-center 70 (my/random-quote)))
'follow-link t
:type (define-button-type 'custom-button
;; https://www.gnu.org/software/emacs/manual/html_node/elisp/Face-Attributes.html
'face (list :foreground "forest green" :slant 'italic)
'help-echo "Click to see another random quote!"))
(setq my/quote-end (point))
(insert "\n\n"))))
(defun my/string-fill-column-and-center (width str)
(with-temp-buffer
(insert str)
(-let [fill-column width] (fill-paragraph))
(center-region (point-min) (point-max))
(buffer-string)))
;;
;; Example usage:
;; (my/string-fill-column-and-center 27 ""We don't think about sinning as you don't think about eating rotten food." ---Imam As-Sadiq")
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
;; MY RANDOM QUOTE ;;
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
;; TODO: When :use_body: is present, get the body but also split the body by “\n\s*-----*”, a line of at least 5 dashes.
(defun my/org-get-title-or-body ()
"Get the title of an Org heading, or its body if tagged with :use_body:."
(interactive)
(save-excursion
(when (org-at-heading-p)
(let ((tags (org-get-tags))
(title (substring-no-properties (org-get-heading t t t t))) ;; Get clean title without keywords or tags
(body (progn
(org-end-of-meta-data)
(buffer-substring-no-properties
(point)
(org-end-of-subtree t t)))))
(if (member "use_body" tags)
(string-trim body)
title)))))
(defun org-get-random-leaf-headline-or-body ()
"
+ Org headlines that have no nested items are called `leaf nodes'.
+ Nesting of sections does not matter.
+ Items marked :use_body: have their body returned instead of title.
+ Sections with children have only their children consulted, as such we can nest arbitrarily without any issues.
+ COMMENTED-out headlines will not be considered
"
(interactive)
(let ((headlines '()))
(org-map-entries
(lambda ()
(unless (org-goto-first-child) ;; Check if the heading has no children
(push (my/org-get-title-or-body) headlines)))
nil ; no tag search, default is nil
nil ; use entire buffer for search, default is nil
'comment) ; skip commented headlines
(seq-random-elt headlines)))
(defun my/random-quote ()
(interactive)
(save-excursion
(save-restriction
;;
(find-file "~/.emacs.d/quotes.org")
(widen)
(-let [quote (org-get-random-leaf-headline-or-body)]
(kill-buffer)
quote))))
#+end_src
** my/consume-content
:PROPERTIES:
:CREATED: [2025-04-09 Wed 16:37]
:END:
#+begin_src emacs-lisp
(defun my/consume-content ()
"This agenda block should display 5 entries, selected uniformly at random
from those entries meeting your selection criteria. Refreshing the
agenda will reshuffle.
Note: Use “g” to refresh and see 5 (new) random entries;
or press “v l 30 RET r” to view 30 entries."
(interactive)
(find-file org-default-notes-file)
(widen)
(beginning-of-buffer)
(search-forward (car (org-ql-query
:select (lambda () (substring-no-properties (thing-at-point 'line)))
:from org-agenda-files
:where '(tags "ConsumeContent")
:order-by (lambda (x y) (pcase (random 3)
(0 nil)
(1 1)
(2 -1)))
;; PR open to get :limit support https://github.com/alphapapa/org-ql/pull/495
;; Note to self: I used https://github.com/emacs-eldev/eldev to run the org-ql tests.
:limit 1))) ;; ⟵ Much faster since I only want 1.
;; (org-tree-to-indirect-buffer) (other-window 1)
(org-narrow-to-subtree))
#+end_src
** Agenda Variables
:PROPERTIES:
:CREATED: [2025-04-13 Sun 09:58]
:END:
#+begin_src emacs-lisp
;; When I clock into a tasg, a “:LOGBOOK:” drawer is created to hold the timing meta-data for the task.
;; When I make document something I've learned with “C-c C-z”, the resulting note should also go into “:LOGBOOK:”.
(setq org-log-into-drawer t)
(setq org-agenda-span 'day)
(setq org-fold-catch-invisible-edits 'show-and-error ;; Avoid accidental edits to folded sections
org-special-ctrl-a/e t ;; C-a/C-e know about leading “*” and ending :tags:
;; Agenda styling
org-agenda-tags-column -80
org-agenda-time-grid '((daily today require-timed)
(800 1000 1200 1400 1600 1800 2000)
" ───── " "───────────────")
org-agenda-current-time-string "◀── now ─────────────────────────────────────────────────")
#+end_src
** How tasks look in org agenda
#+begin_src emacs-lisp
;; Start each agenda item with ‘○’, then show me it's %timestamp and how many
;; times it's been re-%scheduled.
(setq org-agenda-prefix-format " ○ %?-12t%-6e%s ")
(setq org-agenda-deadline-leaders '("DUE: " "In %3d d.: " "%2d d. ago: "))
(setq org-agenda-scheduled-leaders
'("" ;; Don't say “Scheduled ⟨Task⟩”, just show “⟨Task⟩”.
"Overdue%2dx ")) ;; If something's overdue, say “Overdue 𝓃× ⟨Task⟩”.
#+end_src
** COMMENT Pretty Agenda Section Headers :This_is_the_default_behavior:
:PROPERTIES:
:CREATED: [2025-04-13 Sun 09:58]
:END:
#+begin_src emacs-lisp
;; I ran “M-x describe-text-properties” while on an org-agenda heading
;; and saw that it's ‘face’ was ‘org-agenda-structure’, so I ran
;; “C-h o org-agenda-struture” which then give me a button to customize it.
;; So I custimised it, then pressed ‘STATE’ and selected ‘Lisp Expression’,
;; which I paste below.
;;
(set-face-attribute
'org-agenda-structure
nil
;; :background "grey75"
;; :foreground "red"
:weight 'extra-bold
:slant 'normal)
;;
;; Conversely, the getter:
;; (face-attribute 'org-agenda-structure :slant) ;; ⇒ italic
;; Likewise I ran “M-x describe-text-properties” on an item I marked as DONE,
;; but my custom agenda view keeps it around: It's my “what'd make me happy if done this week”
;; section on my agenda. Anyhow, it mentioned that the “face” is “hl-line” and
;; there is a text property “done-face”
;; with value “org-agenda-done”.
;; ❌ (face-attribute 'hl-line 'done-face) ;; ⇒ italic
#+end_src
** COMMENT Sticky Views :No_thanks__org_ql__is_fast:
:PROPERTIES:
:CREATED: [2025-04-13 Sun 09:58]
:END:
#+begin_src emacs-lisp
;; Cache agenda views, unless explicitly refreshed.
;; (This just changes “q” to bury the agenda buffer instead of killing it.)
(setq org-agenda-sticky t)
#+end_src
Sticky agendas allow you to have more than one agenda view created
simultaneously. You can quickly switch to the view without incurring an agenda
rebuild by invoking the agenda custom command key that normally generates the
agenda. If it already exists it will display the existing view.
⇒ ~g~ forces regeneration of the agenda view.
** Show me the agenda when I've been idle for 10 minutes
Basically, if I don't touch Emacs this timer will display my org-agenda
after 10minutes. That can be useful to remember tasks after coming back to
work, or being suggestive to ensure I'm working on the right thing instead of a tangential effort.
#+begin_src emacs-lisp
;; Stop this with: (cancel-function-timers 'my/pop-up-agenda-timer)
(setq my/pop-up-agenda-timer (run-with-idle-timer (* 60 30) t 'my/org-agenda))
#+end_src
This means if I go away for a coffee I'll come back to my agenda reminding what I'm supposed to be working on.
** Get in-Emacs notifications of upcoming appointments by running (org-agenda-to-appt)
<<>>
"Appointments" are [[https://orgmode.org/manual/Special-Agenda-Views.html][defined as]] scheduled tasks with a start time. I occasionally
check them manually, but they are not part of my daily routine because ~M-x
org-agenda-to-appt~ lets me be warned about upcoming ones.
For Org entries with a timestamp involving an hour-minute time, Emacs can warn
you in advance that an appointment is pending. Emacs alerts you to the
appointment by displaying a message in a window along with a beep sound and even
shows a helpful “appointment in 𝓍 minutes” message in the modeline; all
configurable with =appt-display-format= and =appt-audible= and
=appt-display-mode-line=.
#+begin_src emacs-lisp
(require 'appt)
(setq appt-display-duration 30) ;; Show reminder window for 30 seconds please
(setq appt-message-warning-time 12) ;; Show me a warning 12 minutes before an appointment
(setq appt-display-interval 3) ;; Display warning every 3 minutes
;; Ensure all of my Org entries are part of appt whenever it checks for an appointment
(advice-add 'appt-check :before (lambda (&rest args) (org-agenda-to-appt t)))
;; Alterantively: (add-hook 'org-finalize-agenda-hook #'org-agenda-to-appt)
;; `appt-activate' eagerly runs every minute, slow it down to once every 60 minutes
;; Also, don't do anything when I save a file (namely, `appt-update-list').
(advice-add 'appt-activate :after
(lambda (&rest args)
(remove-hook 'write-file-functions #'appt-update-list)
(timer-set-time appt-timer (current-time) (* 60 60))))
#+end_src
We can modify =appt-disp-window-function= (and =appt-delete-window-function=)
so that, for example, we use an operating system pop-up instead of an Emacs window as in:
#+begin_src emacs-lisp
;; (org-show-notification "Attention! You have a meeting in 5 minutes!") ;; Example use.
;; (org-notify "This message has a sound" t) ;; Show pop-up and play a beep.
;; With this, I now see a pop-up notification every `appt-display-interval' minutes
(setq appt-disp-window-function
(lambda (remaining new-time msg)
(org-show-notification (format "⟪In %s minutes⟫ %s" remaining msg))))
#+end_src
*To add (or update) the appointments of your agenda files, use the command
=org-agenda-to-appt=.*
You can also use the appointment notification facility like an alarm clock. The
command =M-x appt-add= adds entries to the appointment list without affecting your
diary file. You delete entries from the appointment list with =M-x appt-delete=.
More:
+ [-] [[https://christiantietze.de/posts/2019/12/emacs-notifications/][Native macOS Notifications for Emacs Org Tasks and Appointments • Christian Tietze]]
- MA: I already have nearly the same setup somehere. See =my-life.org=.
+ [X] [[https://elpa.gnu.org/packages/org-notify.html][GNU ELPA - org-notify]] :: Gives more messaging schemes; e.g., send a message
and an email a few days in advance for deadlines.
+ [ ] [[https://github.com/legalnonsense/org-timed-alerts][GitHub - legalnonsense/org-timed-alerts: Orgmode notification warnings of
upcoming events]]
[[https://www.reddit.com/r/emacs/comments/k0kyi4/comment/gdjyw2w/?utm_source=share&utm_medium=web3x&utm_name=web3xcss&utm_term=1&utm_content=share_button][Author:]] “With regard to other packages, as far as I can tell, org-alert just
bombs alerts about upcoming deadlines. Org-notify doesn't use
libnotify/growl-type notifications and requires setting special
properties. Org-wild-notify is the closest but requires todo keywords or tags,
and doesn't allow much customization of the alert message (e.g., setting the
title or the alert string). For example, I want to know how much time I have
until the event, not just that the event is approaching. I also don't want to
worry about whether I set the proper TODO (or any TODO, really) or tag to get
alerts, hence relying solely on finding timestamps.”
MA: Whereas the built-in ~appt~ works against “appointments”, i.e., scheduled
and timestamped entries, this package only requires a timestamp.
+ [ ] [[https://github.com/spegoraro/org-alert][GitHub - spegoraro/org-alert: System notifications of org agenda items]]
+ [ ] [[https://github.com/akhramov/org-wild-notifier.el?tab=readme-ov-file][GitHub - akhramov/org-wild-notifier.el: Alert notifications for org-agenda]]
+ [ ] [[https://github.com/doppelc/org-notifications][GitHub - doppelc/org-notifications: Desktop notifications for your org-agenda/org-mode items]]
+ [ ] [[https://github.com/unhammer/org-upcoming-modeline/][GitHub - unhammer/org-upcoming-modeline: 📅 Show upcoming org event in modeline]]
MA: Same as ~appt~'s modeline behaviour, but provides additional Org-mode
specific behaivour such as jumping to the task by clicking on the modeline.
** Holy Days & Holidays
In my agenda file, I have
#+begin_src org :tangle no
,* Holidays :Holiday
%%(org-calendar-holiday) ;; special function for holiday names
#+end_src
Which shows the holidays from the list below:
#+begin_src emacs-lisp
(defun my/holiday-islamic (month day event-title url-to-learn-more)
"Make Islamic holidays clickable, and they open URL-TO-LEARN-MORE."
(list 'holiday-islamic month day (propertize event-title
'local-map
(let ((keymap (make-sparse-keymap)))
(define-key keymap (kbd "")
`(lambda() (interactive) (browse-url ,url-to-learn-more)))
keymap))))
(setq calendar-holidays
`(
;; Islamic Holy Days :: https://www.webcal.guru/en/event_list/holidays_islamic_shia?year=2025
;; ﴾1﴿ Muharram, “The Sacred Month” ⨾⨾ ≈ July ’25, Mid-June ’26, June ’27
,(my/holiday-islamic 1 1 "💔🥀 Mourning of Muharram starts" "https://en.wikipedia.org/wiki/Mourning_of_Muharram")
,(my/holiday-islamic 1 2 "💔🥀 Arrival of Imam Husayn ibn Ali in Karbalā, 61 AH" "https://en.wikipedia.org/wiki/Husayn_ibn_Ali")
,(my/holiday-islamic 1 3 "💔🥀 Water supply to the camp of Husayn ibn Ali was stopped" "https://en.wikipedia.org/wiki/Husayn_ibn_Ali")
,(my/holiday-islamic 1 7 "💔🥀 Stored water in the tents of the camp of Husayn ibn Ali runs out" "https://en.wikipedia.org/wiki/Husayn_ibn_Ali")
,(my/holiday-islamic 1 10 "💔🥀 Day of Ashura" "https://ar.wikipedia.org/wiki/%D8%B9%D8%A7%D8%B4%D9%88%D8%B1%D8%A7%D8%A1")
,(my/holiday-islamic 1 12 "💔🥀 Burial of the martyrs of Karbala by Bani Asad" "https://en.wikipedia.org/wiki/Banu_Asad_ibn_Khuzaymah")
,(my/holiday-islamic 1 17 "🐘 Abraha attacked the Kaʿbah in the Year of the Elephant" "https://en.wikipedia.org/wiki/Abraha")
,(my/holiday-islamic 1 18 "🕌 Changing of the Qibla, the direction of prayer" "https://en.wikipedia.org/wiki/Qibla")
,(my/holiday-islamic 1 25 "💔🥀 Martyrdom of Imam Ali ibn Husayn Zayn al-Abidin, 95 AH 🖤" "https://en.wikipedia.org/wiki/Ali_ibn_Husayn_Zayn_al-Abidin")
;; ﴾2﴿ Safar, “Void”
,(my/holiday-islamic 2 1 "💔🥀 Prisoners of Karbalā reach Yazid's palace in Syria" "https://en.wikipedia.org/wiki/Battle_of_Karbala")
,(my/holiday-islamic 2 1 "⚔️ Battle of Siffin, 37 AH" "https://en.wikipedia.org/wiki/Battle_of_Siffin")
,(my/holiday-islamic 2 7 "🥳 Birth of Imam Musa al-Kadhim, 128 AH" "https://en.wikipedia.org/wiki/Musa_al-Kadhim")
,(my/holiday-islamic 2 10 "💔🥀 Martyrdom of Ruqayyah bint Husayn" "https://en.wikipedia.org/wiki/Ruqayyah_bint_Husayn")
,(my/holiday-islamic 2 10 "⚔️ Victory to Ali in the Battle of Nahrawan" "https://en.wikipedia.org/wiki/Battle_of_Nahrawan")
,(my/holiday-islamic 2 12 "🥳 Birth of Salman the Persian" "https://en.wikipedia.org/wiki/Salman_the_Persian")
,(my/holiday-islamic 2 17 "💔🥀 Martyrdom of Imam Ali ar-Ridha, 203 AH" "https://en.wikipedia.org/wiki/Ali_al-Ridha")
,(my/holiday-islamic 2 20 "💔🥀 Ar'baeen, 40th day after Ashura 🖤" "https://en.wikipedia.org/wiki/Arba%CA%BDeen")
,(my/holiday-islamic 2 28 "💔🥀 Martyrdom of Imam Hasan ibn Ali, 50 AH" "https://en.wikipedia.org/wiki/Hasan_ibn_Ali")
,(my/holiday-islamic 2 28 "💔🥀 Martyrdom of Prophet Muhammad, 11 AH" "https://en.wikipedia.org/wiki/Muhammad")
;; ﴾3﴿ Rabi' al-Awwal, “The First Spring”
,(my/holiday-islamic 3 4 "💔🥀 Martyrdom of Fatimah bint Musa" "https://en.wikipedia.org/wiki/Fatimah_bint_Musa")
,(my/holiday-islamic 3 8 "💔🥀 Martyrdom of Imam Hasan al-Askari, 260 AH" "https://en.wikipedia.org/wiki/Hasan_al-Askari")
,(my/holiday-islamic 3 9 "🥳 Eid-e-Zahra" "https://en.wikipedia.org/wiki/Eid-e-Shuja%27")
,(my/holiday-islamic 3 17 "🥳 Birth of Imam Ja'far al-Sadiq, 83 AH" "https://en.wikipedia.org/wiki/Ja%27far_al-Sadiq")
,(my/holiday-islamic 3 17 "🥳 Mulad-al-Nabi: Birth of Prophet Muhammad, 53 BH" "https://en.wikipedia.org/wiki/Mawlid")
,(my/holiday-islamic 3 18 "🥳 Birth of Umm Kulthum bint Ali" "https://en.wikipedia.org/wiki/Umm_Kulthum_bint_Ali")
;; ﴾4﴿ Rabi' al-Thani, “The Second Spring”
,(my/holiday-islamic 4 18 "🥳 Birth of Imam Hasan al-Askari, 232 AH" "https://en.wikipedia.org/wiki/Hasan_al-Askari")
;; ﴾5﴿ Jumada al-Awwal, “The first of parched land”
,(my/holiday-islamic 5 10 "⚔️ Battle of the Camel" "https://en.wikipedia.org/wiki/Battle_of_the_Camel")
,(my/holiday-islamic 5 13 "💔🥀 Martyrdom of Sayedda Fatimah bint Muhammad, 11 AH" "https://en.wikipedia.org/wiki/Fatimah")
;; ﴾6﴿ Jumada al-Thani, “The second of parched land”
,(my/holiday-islamic 6 13 "💔🥀 Death of Umm ul-Banin (mother of Abbas ibn Ali)" "https://en.wikipedia.org/wiki/Umm_al-Banin")
,(my/holiday-islamic 6 20 "🥳 Birth of Sayedda Fatimah bint Muhammad, 8 BH" "https://en.wikipedia.org/wiki/Fatimah")
,(my/holiday-islamic 6 26 "💔🥀 Martyrdom of Imam Ali al-Hadi" "https://en.wikipedia.org/wiki/Ali_al-Hadi")
;; ﴾7﴿ Rajab, “Respect”
,(my/holiday-islamic 7 1 "🥳 Birth of Imam Muhammad al-Baqir, 57 AH" "https://en.wikipedia.org/wiki/Muhammad_al-Baqir")
,(my/holiday-islamic 7 10 "🥳 Birth of Imam Muhammad al-Taqi, 195 AH" "https://en.wikipedia.org/wiki/Muhammad_al-Jawad")
,(my/holiday-islamic 7 13 "🥳 Birth of Imam Ali ibn Abi Talib, 23 BH" "https://en.wikipedia.org/wiki/Ali")
,(my/holiday-islamic 7 15 "💔🥀 Martyrdom of Imam Ja'far al-Sadiq" "https://en.wikipedia.org/wiki/Ja%27far_al-Sadiq")
,(my/holiday-islamic 7 18 "💔🥀 Death of Prophet Abraham" "https://en.wikipedia.org/wiki/Abraham")
,(my/holiday-islamic 7 20 "🥳 Birth of Sukaynah bint Husayn" "https://en.wikipedia.org/wiki/Ruqayyah_bint_Husayn")
,(my/holiday-islamic 7 24 "🥳 Birth of Ali al-Asghar ibn Husayn" "https://en.wikipedia.org/wiki/Ali_al-Asghar_ibn_Husayn")
,(my/holiday-islamic 7 25 "💔🥀 Martyrdom of Imam Musa al-Kadhim" "https://en.wikipedia.org/wiki/Musa_al-Kadhim")
,(my/holiday-islamic 7 26 "💔🥀 Martyrdom of Imam Abu Talib" "https://en.wikipedia.org/wiki/Abu_Talib")
,(my/holiday-islamic 7 27 "🌟 Miʻrāj & day of Mabʻath" "https://en.wikipedia.org/wiki/Isra_and_Mi%27raj")
,(my/holiday-islamic 7 28 "💔🥀 Husayn ibn ‘Alī started his journey to Karbalā from Madinah in 60 AH" "https://en.wikipedia.org/wiki/Husayn_ibn_Ali")
;; ﴾8﴿ Sha'aban, “Scattered”
,(my/holiday-islamic 8 1 "🥳 Birth of Zaynab bint Ali, 6 AH" "https://en.wikipedia.org/wiki/Zaynab_bint_Ali")
,(my/holiday-islamic 8 3 "🥳 Birth of Imam Husayn ibn Ali, 4 AH" "https://en.wikipedia.org/wiki/Husayn_ibn_Ali")
,(my/holiday-islamic 8 4 "🥳 Birth of Abbas ibn Ali, 36 AH" "https://en.wikipedia.org/wiki/Abbas_ibn_Ali")
,(my/holiday-islamic 8 5 "🥳 Birth of Imam Ali ibn Husayn Zayn al-Abidin, 37 AH" "https://en.wikipedia.org/wiki/Ali_ibn_Husayn_Zayn_al-Abidin")
,(my/holiday-islamic 8 11 "🥳 Birth of Ali al-Akbar ibn Husayn" "https://en.wikipedia.org/wiki/Ali_al-Akbar_ibn_Husayn")
,(my/holiday-islamic 8 14 "🥳 Birth of Qasim ibn Hasan" "https://en.wikipedia.org/wiki/Qasim_ibn_Hasan")
,(my/holiday-islamic 8 14 "🌟 Laylat al-Bara'at" "https://en.wikipedia.org/wiki/Mid-Sha%27ban")
,(my/holiday-islamic 8 14 "🌟 Shab-e-barat" "https://en.wikipedia.org/wiki/Shab-e-barat")
,(my/holiday-islamic 8 15 "🥳 Birth of Imam Muhammad al-Mahdi" "https://en.wikipedia.org/wiki/Muhammad_al-Mahdi")
;; ﴾9﴿ Ramadan, “Burning Heat; The Month of Fasting”
,(my/holiday-islamic 9 4 "📜 Descending of the Torah" "https://en.wikipedia.org/wiki/Torah")
,(my/holiday-islamic 9 10 "💔🥀 Death of Khadijah bint Khuwaylid" "https://en.wikipedia.org/wiki/Khadijah_bint_Khuwaylid")
,(my/holiday-islamic 9 12 "📜 Descending of the Gospel" "https://en.wikipedia.org/wiki/Gospel")
,(my/holiday-islamic 9 14 "💔🥀 Martyrdom of Mukhtar ibn Abi Ubayd Al-Thaqafi" "https://en.wikipedia.org/wiki/Mukhtar_al-Thaqafi")
,(my/holiday-islamic 9 15 "🥳 Birth of Imam Hasan ibn Ali" "https://en.wikipedia.org/wiki/Hasan_ibn_Ali")
,(my/holiday-islamic 9 17 "⚔️ Battle of Badr" "https://en.wikipedia.org/wiki/Battle_of_Badr")
,(my/holiday-islamic 9 18 "📜 Descending of the Psalms" "https://en.wikipedia.org/wiki/Psalms")
,(my/holiday-islamic 9 19 "📜 1st night of Laylat al-Qadr" "https://en.wikipedia.org/wiki/Qadr_Night")
,(my/holiday-islamic 9 20 "🌟 Victorious Conquest of Mecca" "https://en.wikipedia.org/wiki/Conquest_of_Mecca")
,(my/holiday-islamic 9 21 "📜 2nd night of Laylat al-Qadr" "https://en.wikipedia.org/wiki/Qadr_Night")
,(my/holiday-islamic 9 23 "📜 3rd night of Laylat al-Qadr" "https://en.wikipedia.org/wiki/Qadr_Night")
,(my/holiday-islamic 9 28 "🌟 Jumu'atul-Wida" "https://en.wikipedia.org/wiki/Jumu%27atul-Wida")
;; ﴾10﴿ Shawwal, “Raised”
,(my/holiday-islamic 10 1 "🥳 Eid al-Fitr" "https://en.wikipedia.org/wiki/Eid_al-Fitr")
,(my/holiday-islamic 10 2 "⚔️ Battle of the Trench" "https://en.wikipedia.org/wiki/Battle_of_the_Trench")
,(my/holiday-islamic 10 8 "💔🥀 Day of Sorrow" "https://en.wikipedia.org/wiki/Day_of_Sorrow")
,(my/holiday-islamic 10 9 "🥳 Marriage of Khadijah bint Khuwaylid to Muhammad" "https://en.wikipedia.org/wiki/Khadija_bint_Khuwaylid")
,(my/holiday-islamic 10 10 "🌟 Major Occultation of Muhammad al-Mahdi begins" "https://en.wikipedia.org/wiki/Major_Occultation")
,(my/holiday-islamic 10 15 "⚔️ Martyrdom of Hamzah in the Battle of Uhud, 3 AH" "https://en.wikipedia.org/wiki/Hamza_ibn_%E2%80%98Abd_al-Muttalib")
,(my/holiday-islamic 10 29 "🥳 Birth of Abu Talib" "https://en.wikipedia.org/wiki/Abu_Talib_ibn_%E2%80%98Abd_al-Muttalib")
;; ﴾11﴿ Dhu al-Qi'dah, “The Month of Truce”
,(my/holiday-islamic 11 1 "🥳 Birth of Fatimah bint Musa" "https://en.wikipedia.org/wiki/Fatimah_bint_Musa")
,(my/holiday-islamic 11 6 "🥳 Treaty of Hudaybiyyah was executed, 6 AH" "https://en.wikipedia.org/wiki/Treaty_of_Hudaybiyyah")
,(my/holiday-islamic 11 11 "🥳 Birth of Imam Ali ar-Ridha, 148 AH" "https://en.wikipedia.org/wiki/Ali_ar-Ridha")
,(my/holiday-islamic 11 25 "🌟 Dahwul Ardh" "https://en.wikishia.net/view/Dahw_al-Ard")
,(my/holiday-islamic 11 29 "💔🥀 Martyrdom of Muhammad al-Taqī, 220 AH" "https://en.wikipedia.org/wiki/Muhammad_al-Taq%C4%AB")
;; ﴾12﴿ Dhu al-Hijjah, “The Month of Pilgrimage”
,(my/holiday-islamic 12 1 "🥳 Marriage of Sayedda Fatimah bint Muhammad to Imam Ali, 2 BH" "https://en.wikipedia.org/wiki/Fatimah_bint_Muhammad")
,(my/holiday-islamic 12 3 "🥳 Renunciation of Adam accepted" "https://en.wikipedia.org/wiki/Adam_in_Islam")
,(my/holiday-islamic 12 7 "💔🥀 Martyrdom of Imam Muhammad al-Baqir, 114 AH" "https://en.wikipedia.org/wiki/Muhammad_al-Baqir")
,(my/holiday-islamic 12 8 "💔🥀 Imam Husayn ibn Ali leaves Makkah for Karbala, 60 AH" "https://en.wikipedia.org/wiki/Husayn_ibn_Ali")
,(my/holiday-islamic 12 9 "🌟 Day of Arafah" "https://en.wikipedia.org/wiki/Day_of_Arafat")
,(my/holiday-islamic 12 9 "💔🥀 Martyrdom of Muslim ibn Aqeel & Hani ibn Urwa in Kufa, 60 AH" "https://en.wikipedia.org/wiki/Muslim_ibn_Aqeel")
,(my/holiday-islamic 12 10 "🥳 Eid al-Adha" "https://en.wikipedia.org/wiki/Eid_al-Adha")
,(my/holiday-islamic 12 15 "🥳 Birth of Imam Ali al-Hadi, 212 AH" "https://en.wikipedia.org/wiki/Ali_al-Hadi")
,(my/holiday-islamic 12 16 "💔🥀 Martyrdom of Sayedda Zaynab bint Ali" "https://en.wikipedia.org/wiki/Zaynab_bint_Ali")
,(my/holiday-islamic 12 18 "🥳 Eid al-Ghadeer" "https://en.wikipedia.org/wiki/Event_of_Ghadir_Khumm")
,(my/holiday-islamic 12 23 "💔🥀 Martyrdom of the children of Muslim ibn Aqeel, 60 AH" "https://en.wikipedia.org/wiki/Muslim_ibn_Aqeel")
,(my/holiday-islamic 12 24 "🥳 Eid al-Mubahalah" "https://en.wikipedia.org/wiki/Event_of_Mubahala")
,(my/holiday-islamic 12 27 "💔🥀 Martyrdom of Maytham al-Tammar, 60 AH" "https://en.wikipedia.org/wiki/Maytham_al-Tammar")
;; Canadian Holidays; https://www.canada.ca/en/revenue-agency/services/tax/public-holidays.html
(holiday-fixed 1 1 "🇨🇦 New Year's Day 🇺🇸")
(holiday-float 2 1 3 "🇨🇦 Family Day") ;; Third Monday in February
(holiday-easter-etc) ;; Good Friday and Easter Monday
(holiday-float 5 1 -1 "🇨🇦 Victoria Day" 25) ;; Monday preceding May 25th
(holiday-fixed 6 1 "🇨🇦 Canada Day")
(holiday-float 8 1 1 "🇨🇦 Civic Holiday") ;; First Monday in August
(holiday-float 9 1 1 "🇨🇦 Labour Day 🇺🇸") ;; First Monday of Septembe
(holiday-fixed 9 30 "🇨🇦 National Day for Truth and Reconciliation")
(holiday-float 10 1 2 "🇨🇦 Canadian Thanksgiving") ;; Second Monday in October
(holiday-fixed 12 25 "🇨🇦 Christmas Day 🇺🇸")
(holiday-fixed 12 26 "🇨🇦 Boxing Day / Day After Christmas 🇺🇸")
;; California Holidays
(holiday-fixed 1 20 "🇺🇸 Martin Luther King Jr. Day")
(holiday-fixed 2 17 "🇺🇸 Presidents’ Day")
(holiday-fixed 5 26 "🇺🇸 Memorial Day")
(holiday-fixed 7 4 "🇺🇸 Independence Day")
(holiday-fixed 11 11 "🇺🇸 Veterans Day")
(holiday-fixed 11 27 "🇺🇸 American Thanksgiving")
(holiday-fixed 11 28 "🇺🇸 Day after Thanksgiving")
;; Misc
(holiday-fixed 2 14 "💕 Valentine's Day")
(holiday-float 5 0 2 "🧕 Mother's Day")
(holiday-float 6 0 3 "👴 Father's Day")
(holiday-fixed 10 31 "👻 Halloween")
(holiday-islamic-new-year)
(solar-equinoxes-solstices)
(holiday-sexp calendar-daylight-savings-starts
(format "Daylight Saving Time Begins %s"
(solar-time-string
(/ calendar-daylight-savings-starts-time (float 60))
calendar-standard-time-zone-name)))
(holiday-sexp calendar-daylight-savings-ends
(format "Daylight Saving Time Ends %s"
(solar-time-string
(/ calendar-daylight-savings-ends-time (float 60))
calendar-daylight-time-zone-name)))))
#+end_src
Also,
+ I see “event ⟪In 𝓃 days⟫” in my agenda, leading up to the event.
- ? (setq org-deadline-warning-days 14)
+ I use the “DEADLINE: ” for dates that I actively want these pre-event reminders; not all holy days.
+ I personally prefer getting advanced warnings of some things coming up that are scheduled, especially if holidays or
birthdays or such so I have some planning time. You can un-comment the below if that isn't you.
- ? (setq org-agenda-skip-deadline-prewarning-if-scheduled t)
#+begin_src emacs-lisp
(defun my/today-and-future (sexpr)
"Returns a list of SEXPR for today and the next `org-deadline-warning-days' days.
If you would like to see upcoming anniversary SEXPR with a bit of
forewarning, you can use the `%%(my/today-and-future SEXPR)`
instead. That will give you `org-deadline-warning-days' days’ warning:
on the anniversary date itself and the `org-deadline-warning-days' many
days prior.
SEXPR should be an expression you normally use in a Diary Sexpr Entry.
The result should be used in Diary Sexpr entries:
It expects a DATE argument to be in scope.
E.g.,
%%(org-calendar-holiday)
Can be replaced by
%%(my/today-and-future '(org-calendar-holiday))
"
(-let [today date
;; '(month day year)
;; For testing:
;; (calendar-gregorian-from-absolute
;; (org-time-string-to-absolute (org-read-date nil nil "today")))
]
(thread-last
(cl-loop for date
from (calendar-absolute-from-gregorian today)
to (+ (calendar-absolute-from-gregorian today) org-deadline-warning-days)
collect (calendar-gregorian-from-absolute date))
(--map
(let* ((agenda-date it)
(org-agenda-current-date it)
;; Rebind 'date' so that SEXPR will
;; be fooled into giving us the list for the given
;; date and then annotate the descriptions for that
;; date.
(date it)
(headline (when-let ((matching-date (eval sexpr))) (or (if (s-blank? (s-trim entry)) nil entry) matching-date))))
;; Note `org-agenda` strips out text styles, so `propertize` is ignored. Sigh.
(when headline (format "%s ⟪%s⟫" headline (org-bbdb-anniversary-description today date)))))
(--filter it))))
(defun org-bbdb-anniversary-description (agenda-date anniv-date)
"Return a string used to incorporate into an agenda anniversary entry.
The calculation of the anniversary description string is based on
the difference between the anniversary date, given as ANNIV-DATE,
and the date on which the entry appears in the agenda, given as
AGENDA-DATE. This makes it possible to have different entries
for the same event depending on if it occurs in the next few days
or far away in the future.
AGENDA-DATE and ANNIV-DATE are both Gregorian; i.e., of the form '(month day year)."
(let ((delta (- (calendar-absolute-from-gregorian anniv-date)
(calendar-absolute-from-gregorian agenda-date))))
(cond
((= delta 0) "Today")
((= delta 1) "Tomorrow")
((< delta org-deadline-warning-days) (format (format "In %d days" delta)))
(t (eval `(format "%02d-%02d-%02d" ,@anniv-date))))))
(cl-defun dates (&key from to)
"Return a list of (month day year) dates from FROM to TO.
FROM and TO are Org-style date strings like \"today\", \"+4d\", \"2025-04-30\"."
(cl-loop for date
from (org-time-string-to-absolute (org-read-date nil nil from))
to (org-time-string-to-absolute (org-read-date nil nil to))
collect (calendar-gregorian-from-absolute date)))
;;
;; (should (equal (dates :from "today" :to "+3d") '((4 22 2025) (4 23 2025) (4 24 2025) (4 25 2025))))
;; Example: Gets a (month day year) date.
;; (calendar-gregorian-from-absolute (org-time-string-to-absolute (org-read-date nil nil "now")))
#+end_src
Finally,
#+begin_src emacs-lisp
(cl-defun date= (month day &optional year)
"To be used in a sexp, so assumes a `date' in scope."
(-let [(m d y) date]
(and (= m month) (= d day) (if year (= y year) t))))
(cl-defun birthday (month day)
"To be used in a sexp, so assumes a `date' and `entry' in scope."
(-let [entry (format "🥳 %s Birthday! 🎂" entry)]
(my/today-and-future `(date= ,month ,day))))
#+end_src
** Display times in agenda in 12-hour AM/PM format
:PROPERTIES:
:CREATED: [2025-04-28 Mon 15:31]
:END:
#+begin_src emacs-lisp
(define-advice org-agenda-format-item (:around (orig &rest args) my/org-agenda-am-pm-time-format)
"Display times in agenda in 12-hour AM/PM format."
(let ((str (apply orig args)))
(replace-regexp-in-string
"\\b\\([0-2]?[0-9]\\):\\([0-5][0-9]\\)\\b"
(lambda (match)
(let* ((hour (string-to-number (match-string 1 match)))
(minute (match-string 2 match))
(ampm (if (>= hour 12) "PM" "AM"))
(hour12 (cond ((= hour 0) 12)
((> hour 12) (- hour 12))
(t hour))))
(format "%d:%s %s" hour12 minute ampm)))
str)))
#+end_src
* ⭕ Workflow States
Workflow states denote /progress/ on a task. For contextual information, we use
/tags/. For example, a delegated task could be in state =STARTED= and tagged
=:delegated:Jasim:=.
My state transitions are:
| ~TODO ⟶ INVESTIGATED ⟶ STARTED ⟷ WAITING ⟷ PAUSED ⟶ DONE ∣ CANCELLED~ |
Note:
+ Org to-do states are just a textual/linear kanban board.
+ Workflow states are also populary known as [[https://www.nimblework.com/kanban/personal-kanban/][“Kanban”]]
** Implementation
Now we can press ~C-c C-t~ then the letter shortcut to actually make the state of an org heading.
#+begin_src emacs-lisp
(setq org-use-fast-todo-selection t) ;; We can also change through states using Shift-⇄.
(setq org-imenu-depth 7)
;; Attempting to move a task to a DONE state is blocked if the has a child task that is not marked as DONE
(setq org-enforce-todo-dependencies t)
#+end_src
First, the my/declare-workflow-states abstraction:
#+begin_src emacs-lisp
(use-package lf)
;; TODO: Add the line “(declare (indent defun))” right after the docstring of “lf-define”,
;; so that Emacs indents it like a “defun”.
;; See https://www.gnu.org/software/emacs/manual/html_node/elisp/Indenting-Macros.html
;;
;; Until then, use the following incantation:
(when (fboundp 'lf-define)
(lf-define (get 'lf-define 'lisp-indent-function) 'defun))
;; (MA: Eventually this function can itself become a small albeit useful MELPA ELisp Package ♥‿♥)
(when (fboundp 'lf-define)
(lf-define my/declare-workflow-states (states)
[:requires (listp states) :ensures (stringp result)]
"Declare STATES as todo-states. STATES is a list of (name on-entry on-exit color) lists.
:on-entry and :on-exit can have the values:
⇒ note ≈ Request the user to add a timestamped note when entering this state.
⇒ timestamp ≈ Automatically log the time that this state was entered.
⇒ unschedule ≈ Unschedule the task when entering this state.
"
;; Declare the keywords and whether they have a note or timestamp on state change
(setq org-todo-keywords (list (cons 'sequence
(cl-loop for (state . props) in states
for first-letter = (downcase (substring state 0 1))
for on-entry = (--when-let (plist-get props :on-entry) (if (listp it) it (list it)))
for on-exit = (--when-let (plist-get props :on-exit) (if (listp it) it (list it)))
;; Assert: on-entry is a list, on-exit is a list
for entry = (cond ((member 'note on-entry) "@") ((member 'timestamp on-entry) "!") (t ""))
for exit = (cond ((member 'note on-exit) "/@") ((member 'timestamp on-exit) "/!") (t ""))
collect (if (equal state "|") state (format "%s(%s%s%s)" state first-letter entry exit))))))
;; Colour the keywords
(setq org-todo-keyword-faces
(cl-loop for (state . props) in states
collect (list state :foreground (plist-get props :foreground) :weight 'bold)))
;; Account for ‘unschedule’ action
;; When a task goes into the state STATE, please remove its schedule
;; so that it does not appear in my agenda. (However, it's still not “done” and so appears when I do “C-c a t” for example.)
;; Source: https://emacs.stackexchange.com/a/2760
(cl-loop for (state . props) in states
do
(when (member 'unschedule (plist-get props :on-entry))
;; TODO: Need to remove-hook “my/remove-schedule--⟨STATE⟩” to account for running this my/declare-workflow multiple times and expecting these hooks to not be present, say the second time around!
(add-hook 'org-after-todo-state-change-hook
(eval `(defun ,(intern (concat "my/remove-schedule--" state)) ()
"Remove SCHEDULED-cookie when switching state to STATE."
(save-excursion
(and (equal (org-get-todo-state) ,state)
(org-get-scheduled-time (point))
(when (search-forward-regexp org-scheduled-time-regexp nil t)
(or (delete-region (match-beginning 0) (match-end 0)) t))
(get-buffer "*Org Agenda*")
(with-current-buffer "*Org Agenda*"
(org-agenda-redo)))))))))
;; End
"✔ Invoke `org-mode-restart` in existing Org buffers for this to take effect."))
#+end_src
Then, actually declare my workflow states...
#+begin_src emacs-lisp
(when (fboundp 'my/declare-workflow-states)
(my/declare-workflow-states
;; Transitions: TODO → INVESTIGATED → STARTED ⟷ {AWAITING_REVIEW | PAUSED} → {DONE | CANCELLED}
;; (M-q via (setq fill-column 95) and M-x my/comment-box)
'(
("TODO" :foreground "red") ;; A task was captured into my inbox.
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
;; Tasks that are not started and not planned. They could be the backlogs or the GTD’s ;;
;; someday/maybe. These tasks could be converted to NEXT INVESTIGATED during a weekly ;;
;; review. ;;
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
("INVESTIGATED" :foreground "dark orange") ;; Tasks that are *ready* to be started next.
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
;; These are tasks that are not started but I plan to do as soon as I can. When there is no ;;
;; actionable STARTED task, I start one of the INVESTIGATED and convert it to STARTED. ;;
;; ;;
;; The problem with most todo-lists is that you get overwhelmed by the amount of stuff to be ;;
;; done. But in reality, most actions don't need or can't be progressed. So rather than look ;;
;; at all the TODO tasks, we can limit our view to only the INVESTIGATED tasks. ;;
;; 💡 Instead of massive lists of things you'd like to do some day, have concrete NEXT ;;
;; actions to undertake to achieve your goals. This way, only a subset of realistic ;;
;; activities is in your consciousness. 💡 ;;
;; ;;
;; Ideally, a task moves from TODO to NEXT only when I've actually split the task into small ;;
;; achievable chunks; ie i've done some investigation into the task and thought about ;;
;; what steps I need to do to actually get the task done. With this planning in place, I ;;
;; can then ensure I allocate sufficient timeblocks to work on the subtasks of this ;;
;; task. The investigation stage is about clarifying: ;;
;; - What “done” means for the task, ;;
;; - /why/ am I doing this task; i.e., what are the benefits of the task; ;;
;; - Including background information; e.g., external links or a paragraph; ;;
;; - Splitting the task into achievable sub-tasks, so that it's not nebulous ;;
;; and so too daunting to start. ;;
;; ;;
;; 🤔 Tip: Use my 1/1 time with my manager/peers to review my INVESTIGATED/NEXT/READY ;;
;; findings for the tickets of the current sprint. I just want to make sure I'm on the right ;;
;; track, before starting to work on them. Or, if a ticket is not investigated, do that with ;;
;; my manager. I find that while it might take me half an hour or more, it'll take like 5 ;;
;; minutes with him since he's familiar with the code-base. ;;
;; ;;
;; (Aside: Some people use a “NEXT” state to denote “this task is the /next/ immediate task ;;
;; to do in this project”. Since my tasks are ordered, the NEXT task would be the first ;;
;; task that is “TODO” or “INVESTIGATED”.) ;;
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
("STARTED" :foreground "blue") ;; I've begun this task, and it's loaded into my short-term memory.
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
;; These are tasks that are working in progress (“open loops”). I work on these tasks before ;;
;; starting another NEXT task to avoid too many open loops at any moment. ;;
;; ;;
;; Whenever I clock-into a task, it is automatically transitioned into this state. As such, ;;
;; if I want know when I first started on a task, I simply look at the CLOCK entry it has. ;;
;; ;;
;; Note: “:on-entry timestamp” is not ideal for my current use since my tasks tend to ;;
;; ping-pong between STARTED ⟷ WAITING. ;;
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
("|")
;; All states after this special marker are “terminal” and so not shown in the org-agenda:
;; (setq org-agenda-skip-scheduled-if-done t)
;;
;; Moreover, they are counted as “done” in the statistics “ [96%] ” count of a parent heading.
;;
;; Finally, I get a “CLOSED: ” property on these tasks when
;; (setq org-log-done 'time). This is desirable, since it tells me when I entered these ‘terminal’
;; states: E.g., how long ago a task entered the WAITING state.
;;
;; Also, the definition of “done” in Org-QL includes all terminal states in my workflow, yay.
("PAUSED" :on-entry 'note :on-exit 'timestamp :foreground "magenta") ;; I'm not actively working on this task anymore. I may return to it later.
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
;; I am choosing to stop work on this task for some reason; e.g., it is no longer a priority ;;
;; (i.e., I'm not interested in it, or I realised it does not contribute to my long-term ;;
;; life goals). ;;
;; ;;
;; When I enter this state, record when & why the task is paused. ;;
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
("WAITING" :on-entry 'unschedule :foreground "red2") ;; I'm waiting on feedback from others before I can continue.
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
;; When a task goes into WAITING, I've finished the task as much as possible and now need to ;;
;; rely on someone else; e.g., for feedback. I'm waiting on *someone else*. ;;
;; ;;
;; ⇒ I don't want to see these scheduled tasks in my Agenda. ;;
;; ⇒ If I'm waiting on an email, I can make an Org task to track the fact I'm waiting on it. ;;
;; ⇒ In the Weekly Review, I will take time to look at my WAITING tasks ;;
;; and if they've been waiting ~2 weeks, then I should message the relevant people to unblock it. ;;
;; ;;
;; Waiting = “In progress, but BLOCKED by others” ;;
;; ;;
;; 🤔 Consider adding a WAITING_SINCE property whenever a task enters this state, so that I ;;
;; can reach out to others and say “I've been waiting on you since Jan 1, please unblock ;;
;; me!” ;;
;; ;;
;; “:on-entry timestamp” is not ideal for my current use since my tasks tend to ping-pong ;;
;; between STARTED ⟷ WAITING. ;;
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
("APPROVED" :foreground "magenta") ;; Almost done, just needs a quick review.
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
;; I'm actively working on this task, and not waiting on any one else, ;;
;; but there is some blocker; e.g., a merge dependency issue or a conflict to resolve. ;;
;; Sometimes these are quick to dispatch; other times they're blocked by PAUSED/WAITING tasks. ;;
;; ;;
;; This is essentially DONE, but there's some blocker. ;;
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
("DONE" :foreground "forest green") ;; This task is DONE; mine it for useful LOG comments and archive it.
("CANCELLED" :on-entry 'note :foreground "saddle brown") ;; Why was this task cancelled? (Notes come with a timestamp!)
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
;; I've started on this task and now realised /I do not want/ continue this approach, and so ;;
;; will ABANDON it. This is useful at work to keep track of *why* we have decided against ;;
;; doing a task; in my Org file there may be more, private, reasons not mentioned in the ;;
;; company's Jira file. (For example). ;;
;; ;;
;; Instead of just deleting the task, I document it so that if I have the same idea/task ;;
;; again then I can see my notes to figure out /why/ I didn't do it last time. Also useful ;;
;; for when doing Annual Reviews: Why did I quit these tasks. ;;
;; ;;
;; The logging is helpful if others at work want to know why some approach was abandoned, so ;;
;; TAKE A MINUTE TO FLESH OUT THE REASONS FOR CANCELLATION. ;;
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
)))
#+end_src
*** Also, logging
#+begin_src emacs-lisp
;; Since DONE is a terminal state, it has no exit-action.
;; Let's explicitly indicate time should be noted.
(setq org-log-done 'time)
;; → Take a look at org-log-done and org-log-into-drawer. These will tell org to log the date and time when an item's status is changed (you can specify).
;; → When the agenda is built you can show all these logged items on the date they were completed with org-agenda-log-mode, org-agenda-log-mode-items, and org-agenda-start-with-log-mode.
;; → This allows me to place TODO items anywhere I want (my logbook, notes, and a scratch list) and as I complete them through the week they're all shown in the agenda according to when I completed each.
;; → I use org-clock-in to the task I'm working on, then a simple clocktable with some dates will show me exactly what I worked on.
;; → [Weekly Review] which creates a day-by-day summary of the time I worked on what tasks. On Friday, I can look at this and see what I did over the week.
;;
;; clocking-in is about the best way to answer that dreaded Friday afternoon question: "WTF did I do with my time this week/month/etc!?"
;; I prefer to log TODO creation also
(setq org-treat-insert-todo-heading-as-state-change t)
;; Use S-⇆ as a convenient way to select a TODO state and bypass any logging associated with that.
;; E.g., a task is STARTED and pressing S-→ moves it to PAUSED /without/ having to add a note for why it's now paused.
(setq org-treat-S-cursor-todo-selection-as-state-change nil)
#+end_src
** Propagate =STARTED= to parent tasks
:PROPERTIES:
:CREATED: [2024-05-08 Wed 15:38]
:END:
When a task is marked =STARTED=, the STARTED state propagates up the tree to any
parent tasks of this task that have any =TODO= state. This helps me keep track of
things that are in progress.
#+begin_src emacs-lisp
(add-hook 'org-after-todo-state-change-hook
(defun my/if-I-am-STARTED-task-so-is-my-project-parent ()
(when (equal (org-get-todo-state) "STARTED")
(save-excursion
;; Change all parents /that/ have a todo keyword
(while (org-up-heading-safe)
(when (org-get-todo-state) (org-todo "STARTED")))))))
#+end_src
** COMMENT Let's draw a state diagram to show what such a workflow looks like. :Posterity:
[[http://plantuml.com/index][PlantUML]] supports drawing diagrams in a tremendously simple format
---it even supports Graphviz/DOT directly and many other formats.
Super simple setup instructions can be found [[http://eschulte.github.io/babel-dev/DONE-integrate-plantuml-support.html][here]]; below are a bit more
involved instructions. Read the manual [[http://plantuml.com/guide][here]].
#+begin_src emacs-lisp
;; Install the tool
; (async-shell-command "brew tap adoptopenjdk/openjdk; brew cask install adoptopenjdk13") ;; Dependency
; (async-shell-command "brew install plantuml")
;; Tell emacs where it is.
;; E.g., (shell-command-to-string "find / -name plantuml.jar")
;; (setq org-plantuml-jar-path "/usr/local/Cellar/plantuml/1.2022.14/libexec/plantuml.jar")
(setq org-plantuml-jar-path "/opt/homebrew/Cellar/plantuml/1.2025.2/libexec/plantuml.jar")
;; Enable C-c C-c to generate diagrams from plantuml src blocks.
(add-to-list 'org-babel-load-languages '(plantuml . t) )
(use-package ob-plantuml :defer t)
; Use fundamental mode when editing plantuml blocks with C-c '
(add-to-list 'org-src-lang-modes '("plantuml" . fundamental-mode)
#+end_src
#
# (async-shell-command "cp workflow.png ~/alhassy.github.io/assets/img/")
Let's use this!
# The source block is replaced with the generated image in-place, by default.
# #+begin_src plantuml :file workflow.png :exports code :cache (progn (async-shell-command "cp workflow.png ~/alhassy.github.io/assets/img/") "yes")
#+begin_src plantuml :file images/workflow.png :tangle no :exports both :eval never-export :results replace
skinparam defaultTextAlignment center /' Text alignment '/
skinparam titleBorderRoundCorner 15
skinparam titleBorderThickness 2
skinparam titleBorderColor red
skinparam titleBackgroundColor Aqua-CadetBlue
title My Personal Task States
[*] -> Todo /' This is my starting state '/
Done -right-> [*] /' This is an end state '/
Cancelled -up-> [*] /' This is an end state '/
/'A task is “Todo”, then it's “started”, then finally it's “done”. '/
Todo -right-> Started
Started -down-> Waiting
Waiting -up-> Started
Started -right-> Done
/'Along the way, I may pause the task for some reason then
return to it. This may be since I'm “Blocked” since I need
something, or the task has been put on “hold” since it may not
be important right now, and it may be “cancelled” eventually.
'/
Todo -down-> Waiting
Waiting -up-> Todo
Waiting -up-> Done
Todo -down-> On_Hold
On_Hold -> Todo
On_Hold -down-> Cancelled
Waiting -down-> Cancelled
Todo -down-> Cancelled
/' The Org-mode shortcuts for these states are as follows. '/
Todo : t
On_Hold : h
Started : s
Waiting : w
Cancelled : c
Done : d
/' If a task is paused, we should document why this is the case. '/
note right of Waiting: Note what is\nblocking us.
note right of Cancelled: Note reason\nfor cancellation.
note bottom of On_Hold: Note reason\nfor reduced priority.
center footer ♥‿♥ Org-mode is so cool (•̀ᴗ•́)و
/' Note that we could omit the “center, left, right” if we wished,
or used a “header” instead.'/
#+end_src
#+RESULTS:
[[file:images/workflow.png]]
# (org-display-inline-images t t)
# (shell-command "rm workflow.png")
# +HTML: 
Of note:
+ Multiline comments are with ~/' comment here '/~, single quote starts a one-line comment.
+ Nodes don't need to be declared, and their names may contain spaces if they are enclosed in double-quotes.
+ One forms an arrow between two nodes by writing a line with ~x ->[label here] y~
or ~y <- x~; or using ~-->~ and ~<--~ for dashed lines. The label is optional.
To enforce a particular layout, use ~-X->~ where ~X ∈ {up, down, right, left}~.
+ To declare that a node ~x~ has fields ~d, f~ we make two new lines having
~x : f~ and ~x : d~.
+ One adds a note near a node ~x~ as follows: ~note right of x: words then newline\nthen more words~.
Likewise for notes on the ~left, top, bottom~.
- A note can be on several lines. It's terminated by ~end note~.
+ Interesting sprites and many other things can be done with PlantUML. Read the docs.
This particular workflow is inspired by [[http://doc.norang.ca/org-mode.html][Bernt Hansen]] ---while quickly searching
through the PlantUML [[http://plantuml.com/guide][manual]]: The above is known as an “activity diagram” and
it's covered in §4.
Org-mode may be used with PlantUML:
+ See §11,12 for using Org-mode notation to form ‘mindmaps’ and ‘work breakdown
structures’.
+ Org-mode text formatters are also acknowledged but the delimiters must be
doubled; see §16.1.
You can quickly write and see the resulting UMLs using
https://liveuml.com/, for the most part.
** [#C] COMMENT ON_STARTED, ON_DONE, ON_XYZ
:PROPERTIES:
:CREATED: [2024-05-09 Thu 08:01]
:END:
#+begin_src emacs-lisp
;; Run hooks “ON_[STARTED∣DONE]” state changes.
;; (MA: Consider adding “ON_𝒳” for all states 𝒳, using above workflow loop.)
;; (MA: Consider turning the example /below/ into a single property hook, say “:TEMPORARILY_TREAT_SUBTREES_AS_CHECKBOXES: t”)
;;
;; For example, in the following, when we press “t s” to put “A” into “STARTED A” the declared code is run:
;; It essentially treats all children trees, temporarily, as checkboxes: Pressing “t” toggles between “ ∣ TODO ∣ DONE”
;; and does not log any info about state change of the subtrees. (Also, the “STARTED A” is becomes “A”).
;; Then when we press “t” on “A” we get “DONE A”, which invokes the associated ON_DONE code, which just resets things to before
;; we began working on task “A”.
;;
;; ** A
;; :PROPERTIES:
;; :ON_STARTED: (progn (if (search-forward-regexp org-todo-regexp nil t) (or (delete-region (match-beginning 0) (match-end 0)) t)) (setq remember/org-todo-keywords org-todo-keywords) (setq org-todo-keywords '("TODO" "DONE")) (setq remember/org-log-done org-log-done) (setq org-log-done nil) (org-mode-restart))
;; :ON_DONE: (progn (setq org-todo-keywords remember/org-todo-keywords org-log-done remember/org-log-done) (org-mode-restart))
;; :END:
;;
;; *** TODO B
;;
(add-hook
'org-after-todo-state-change-hook
(defun my/special-ON_STARTED-property-hook ()
"When a task enters STARTED/DONE state, execute the code in its ON_STARTED/ON_DONE property."
(save-excursion
(save-restriction
;; yet another property support
(when (equal (org-get-todo-state) "TODO")
;; Instead of ignore-errors, it should only evaluate the string /if/ it is present.
(ignore-errors (eval (car (read-from-string (eval (org-entry-get (point) "ON_TODO")))))))
;; yet another property support
(when (equal (org-get-todo-state) "STARTED")
;; Instead of ignore-errors, it should only evaluate the string /if/ it is present.
(ignore-errors (eval (car (read-from-string (eval (org-entry-get (point) "ON_STARTED")))))))
;; yet another property support
(when (equal (org-get-todo-state) "DONE")
;; Instead of ignore-errors, it should only evaluate the string /if/ it is present.
(ignore-errors (eval (car (read-from-string (eval (org-entry-get (point) "ON_DONE")))))))
;; yet another property support -- AXE?
(when (equal "t" (org-entry-get (point) "TEMPORARILY_TREAT_SUBTREES_AS_CHECKBOXES"))
(when (equal (org-get-todo-state) "TODO")
(let ((current-prefix-arg :random-theme)) (my/toggle-theme))
(org-narrow-to-subtree)
(beginning-of-buffer)
(setq remember/org-todo-keywords org-todo-keywords
org-todo-keywords '("TODO" "DONE")
remember/org-log-done org-log-done
org-log-done nil
remember/org-log-note-headings org-log-note-headings
org-log-note-headings nil)
(org-mode-restart))
(when (or (equal (org-get-todo-state) "DONE") (equal (org-get-todo-state) ""))
(setq org-todo-keywords remember/org-todo-keywords
org-log-done remember/org-log-done
org-log-note-headings remember/org-log-note-headings)
(org-mode-restart)))))))
#+end_src
#+RESULTS:
| my/special-ON_STARTED-property-hook | my/remove-schedule--WAITING |
** TODO COMMENT Music for DONE state
:PROPERTIES:
:CREATED: [2025-01-10 Fri 15:33]
:END:
- *Music and sound effects:* There is a reason that chimes and trumpets
sound when you successfully perform a task or reach a goal in a
videogame or slot machine. Pleasure is a reward, and pleasant sights
and sounds produce pleasure.
* ✏️ Capturing Content: Links, Smart Paste, Attachments, and Org Rifle
:PROPERTIES:
:CREATED: [2025-04-14 Mon 09:43]
:END:
** Capture: Now that I know how to query my agenda, how do I get things into it efficiently?
:PROPERTIES:
:CREATED: [2025-04-14 Mon 09:29]
:END:
An important part of any organization system is the ability to quickly /capture/ new ideas and tasks, and to associate
reference material with them. It also can store files related to a task (/attachments/) in a special directory. Finally,
it can parse RSS feeds for information.
It is often useful to associate reference material with an outline node. Small chunks of plain text can simply be
stored in the subtree of a project. Hyperlinks (see [[https://orgmode.org/manual/Hyperlinks.html][Hyperlinks]]) can establish associations with files that live
elsewhere on a local, or even remote, computer, like emails or source code files belonging to a project. Another method
is [[https://orgmode.org/manual/Attachments.html][/attachments/]], which are files located in a directory belonging to an outline node.
#+begin_src emacs-lisp
(eval-and-compile (require 's nil t)) ;; Needed for s-replace-regexp in def-capture macro
(declare-function s-replace-regexp "s" (regexp replacement s &optional literal))
(declare-function s-contains\? "s" (needle s &optional ignore-case))
(declare-function s-replace "s" (old new s))
(declare-function s-trim "s" (s))
(cl-defmacro def-capture (name location template &rest forms)
"Creates a method “my/capture-NAME”, which opens a capture buffer named NAME showing TEMPLATE.
When you press `C-c C-c`, the note is saved as an entry (ie TEMPLATE should start with “* ”.)
in `org-default-notes-file' section named LOCATION.
+ NAME, LOCATION, TEMPLATE are all strings that may contain spaces.
⇒ If you want to evaluate a function in TEMPLATE and have its results be inlined, use the syntax “%(f args)”.
See https://stackoverflow.com/a/69331239 for an example.
⇒ See the docs of `org-capture-templates', half-way down, for supported %-escapes in the template.
+ FORMS is an optional collection of Elisp forms to execute after a capture template session has been initiated;
e.g., to programmatically add content to a template, say a quote or the results of a shell command.
+ Example: (def-capture \"Friends Info\" \"Journal\" \"* %t\" (message \"Well-done! Stay in touch!\"))
This can be used as “M-x my/capture-friends-info” or via an Org link: “[[elisp:( my/capture-friends-info)]]”.
Note: My “Journal” is nested in a section called “Workflow”, and capture finds it anyways (｡◕‿◕｡)
(More precisely, Org-Capture looks for the first (sub)headline called “Journal” /anywhere/ and uses that as the target location.)
Usage:
1. M-x my/capture-NAME ⇒ Capture something to my LOCATION; no menu used.
2. C-u M-x my/capture-NAME ⇒ Jump to my LOCATION.
3. C-u C-u M-x my/capture-NAME ⇒ Goto last note stored (by any my/capture-* method).
"
`(defun ,(intern (concat "my/capture-" (replace-regexp-in-string " " "-" (downcase name)))) (&optional prefix)
(interactive "p")
(let (;; Temporarily pause any clocking hooks
(org-clock-in-hook nil)
(org-clock-out-hook nil)
(org-capture-templates
;; Capture mode now handles automatically clocking in and out of a capture task.
;; When I start a capture mode task the task is clocked in as specified by :clock-in t
;; and when the task is filed with C-c C-c the clock resumes on the original clocking task.
`(("𝒞" ,,name entry (file+headline "~/Dropbox/my-life.org" ,,location) ,,template :clock-in t :clock-resume t))))
(org-capture (list prefix) "𝒞")
(unless (> prefix 1) (rename-buffer ,name))
,@forms)))
(unless noninteractive
(eval '(bind-key* "C-c c" (def-capture "Inbox Entry 📩" "Inbox 📩 \t\t\t:inbox:" "* TODO %?\n:PROPERTIES:\n:CREATED: %U\n:END:\n"))))
#+end_src
My other primary use of ~def-capture~ is for 〔Daily ∣ Weekly ∣ Monthly ∣ Bi-Annual〕reviews.
** Persistent Scratch Buffer :Disabled:
:PROPERTIES:
:CUSTOM_ID: Persistent-Scratch-Buffer
:header-args: :tangle no
:END:
The ~*scratch*~ buffer is a nice playground for temporary data or experiments.
However, by default its contents are not saved --which may be an issue if we
have not relocated our playthings to their appropriate files. Whence let's save
& restore the scratch buffer by default.
#+begin_src emacs-lisp
(use-package persistent-scratch
;; In this mode, the usual save key saves to the underlying persistent file.
:bind (:map persistent-scratch-mode-map ("C-x C-s" . persistent-scratch-save)))
#+end_src
We might accidentally close this buffer, so we could utilise the following.
#+begin_src emacs-lisp
(defun scratch ()
"Recreate the scratch buffer, loading any persistent state."
(interactive)
(switch-to-buffer-other-window (get-buffer-create "*scratch*"))
(condition-case nil (persistent-scratch-restore) (insert initial-scratch-message))
(org-mode)
(persistent-scratch-mode)
(persistent-scratch-autosave-mode 1))
;; This doubles as a quick way to avoid the common formula: C-x b RET *scratch*
;; Upon startup, close the default scratch buffer and open one as specfied above
(ignore-errors (kill-buffer "*scratch*") (scratch))
#+end_src
I use Org-mode often, so that's how I want things to appear.
#+begin_src emacs-lisp
(setq initial-scratch-message (concat
"#+title: Persistent Scratch Buffer"
"\n#\n# Welcome! This’ a place for trying things out."
"\n#\n# ⟨ ‘C-x C-s’ here saves to ~/.emacs.d/.persistent-scratch ⟩ \n\n"))
#+end_src
** Adding New *Tasks/Notes* Quickly Without Disturbing The Current Task Content
New sections can be created conveniently by simply modifying the ~RETURN~ key:
+ M-RET :: New Org item, if near an itemisation; else a new heading /here/.
+ M-S-RET :: New Org checkbox, if near an itemisation; else a new ~TODO~ heading /here/.
+ C-RET :: New Org heading /after/ the current section.
+ C-S-RET :: New ~TODO~ heading /after/ the current section.
For example, in the middle of an entry I can press ~C-RET~ to make a new heading
/at the end/ of the current entry. Alternatively, I can /split/ the current entry in
the middle with ~M-RET~.
Finally, every time I create a heading using a modified ~RETURN~, I automatically
insert an inactive timestamp indicating when the headline is created (unless I
press ~C-u~ first).
#+begin_src emacs-lisp
(add-hook
'org-insert-heading-hook
(defun my/insert-CREATED-property ()
"Insert :CREATED: property upon C-[S]-RET and M-[S]-RET, unless C-u is pressed first."
(unless current-prefix-arg
(org-set-property "CREATED" (format-time-string "[%Y-%m-%d %a %H:%M]")))))
;; I also have a short cut key defined to invoke this function on demand so that
;; I can insert the inactive timestamp anywhere on demand.
;;
;; I use TAB and S-TAB for cycling - I don't need c and C as well.
;; Instead use “c” to add the ‘C’reated property.
(setf (cdr (assoc "c" org-speed-commands)) #'my/insert-CREATED-property)
#+end_src
Finally, when I'm working in a itemisation, I usually want an /indented/ newline whenever I
press ~RETURN~.
#+BEGIN_SRC emacs-lisp
(add-hook 'org-mode-hook '(lambda ()
(local-set-key (kbd "") 'org-return-indent)) ;; Newline with indentation
(local-set-key (kbd "C-M-") 'electric-indent-just-newline)) ;; Newline without indentation
#+END_SRC
/Importantly, a ‘task’ is a reminder for me to do something! If a
reminder is not required, then perhaps I have a ‘note’./
/Not everything needs to be a task./
*** Hide blank lines /between/ headlines
#+begin_src emacs-lisp
(setq org-cycle-separator-lines 0)
(setq org-blank-before-new-entry '((heading) (plain-list-item . auto)))
#+end_src
** “Smart Paste”: Drag and Drop Images/(Any File!) into Org-Mode :ATTACH:
:PROPERTIES:
:CUSTOM_ID: drag-and-drop-images-into-org-mode
:ID: AD6BB33A-C860-45A0-936F-3B59CE4FFA14
:END:
When I press ~⌘-v~, here's what I'd like to happen to my clipboard contents:
1. If it's an image, then ‘attach’ it to the current Org section and insert a link to the image.
2. If it's a Gerrit URL such as
~12345: [foo, bar] OCaml Syntax: Fix foo bar baz | https://gerrit.local.company.com/c/abc/+/12345~
then produce a nice Org link to it.
3. If it's an arbitrary URL, then try to retrive its title and produce a nice Org link to it.
4. If it's rich text (e.g., something copied from a webpage, including code blocks), then try to
preserve the formatting using Org markup.
5. Otherwise, do a plain-old paste.
For instance, now I can do:
1. Take a screenshot with ~cmd + space + screenshot~ then take the screenshot, then just drag the result into my note.
1. Or just ~M-x org-download-screenshot~
2. Click “Copy Image” in some app, then in Emacs invoke ~M-x org-download-clipboard~
3. Find an image in some app, then drag-and-drop it into my note.
4. Drag a file, such as a PDF, into my note to make it into an attachement!
Implementation:
#+begin_src emacs-lisp
(add-hook
'org-mode-hook
(cl-defun my/setup-smart-paste ()
(interactive)
(require 'cl)
(bind-key "s-v"
(cl-defun my/dwim-paste ()
"Call `yank-media', with first possible media-type; ie no prompting.
With “C-u” prefix, or when in minibuffer, this is traditional paste.
Otherwise, if clipboard contains:
+ Rich Text (i.e., copy of HTML text), then it's pasted as Org Markup.
+ Image, then it's attached to the current Org note, via `org-attach', and an “attachement:” link is pasted
and the image link is displayed inline.
+ If it's a Gerrit link, “12345: [tags] Fix parsing bug | ”, then produce “[[][Fix parsing bug]]”.
+ Otherwise, default string plaintext pasting occurs.
- If string is a URL, then insert an Org link whose description is HTML title of that URL webpage.
,* If a region is selected when the yank is performed, then that region becomes the description of the link.
TODO:
⇒ If text is selected when I past an image, then use the text as #+caption, maybe?
⇒ Define “attachement:” using org-special-block-extras so that it gives me keymap options like
delete attachement, rename attachement, open attachement externally, open in emacs. Low priority.
"
(interactive)
(if (or (minibufferp) current-prefix-arg (null yank-media--registered-handlers))
(yank)
(flet ((length= (&rest _args) 'assume-equality-check-is-true-in--implementation))
(-let [start (point)]
(ignore-errors (yank-media))
;; If no media to yank, then do plain old yank
(when (equal start (point)) (yank)))))))
;; Added to: yank-media--registered-handlers.
(yank-media-handler
"text/html"
(cl-defun my/yank-html-media (_media-type contents)
(insert (s-replace " " " " (shell-command-to-string
(-let [delimiter "EOF"] ;; A unique “here-document delimiter”, unlikely to be part of ‘contents’
;; NOTE: `shell-quote-argument` does too much here; e.g., copied code blocks wont paste nicely.
;; For now, I want $FOO to be pasted as itself, and not interpreted as a Shell variable.
(format "pandoc -f html -t org <<%s\n%s\n%s" delimiter
;; Often at work people use backticks as code markers, so transform that to
;; ~org syntax~. This also avoids breaking the shell call, since backquote means
;; inline-eval in shell; e.g., echo `echo hello`world ⇒ helloworld
;; likewise: echo `pwd`world ⇒ ⟨current directory⟩world
(s-replace "`" "~" (s-replace "$" "\\$" contents))
delimiter)))))))
(yank-media-handler
"STRING"
(cl-defun my/yank-plaintext-media (_media-type contents)
(let* ((url (when (string-match-p "^https?://" contents) contents))
(region-content (when (region-active-p)
(buffer-substring-no-properties (region-beginning)
(region-end)))))
(cond ((and region-content url)
(delete-region (region-beginning) (region-end))
(insert (org-make-link-string url region-content)))
(url
;; Insert Org link to URL using title of HTML page at URL.
(org-web-tools-insert-link-for-url url))
(:otherwise
(-let [ (gerrit-title gerrit-url) (my/extract-gerrit-title-and-url contents) ]
(if (and gerrit-title gerrit-url)
(insert (org-make-link-string gerrit-url gerrit-title))
(insert contents))))))))
;;
(defun my/extract-gerrit-title-and-url (str)
"Extract the title and URL from the given string STR, omitting the leading number and tags in brackets."
(if (string-match "^\\(?:[0-9]+: \\)?\\(?:\\[[^]]+\\] \\)?\\(.*?\\) | \\(https?://[^ \"]+\\) *$" str)
(let ((title (match-string 1 str))
(url (match-string 2 str)))
(list title url))))
;; example usage
(when nil
(let ((input "12345: [foo, bar] OCaml Syntax: Fix foo bar baz | https://gerrit.local.company.com/c/abc/+/12345"))
(-let [ (title url) (my/extract-gerrit-title-and-url input) ]
(message "Title: %s\nURL: %s" title url))))
(yank-media-handler
"image/.*"
(cl-defun my/yank-image-media (_media-type image)
(org--image-yank-media-handler 'image/png image)
(my/toggle-display-inline-image-at-point)))
;; Used by org--image-yank-media-handler
(defun org-yank-image-autogen-filename ()
"Autogenerate filename for image in clipboard."
(format-time-string "%Y-%m-%d_%I:%M:%S%p"))
(cl-defun my/toggle-display-inline-image-at-point ()
"My single notes file is huge, so toggling all images takes a while. Whence this method."
(interactive)
(-let [inhibit-message t]
(beginning-of-line)
(push-mark)
(end-of-line)
(org-toggle-inline-images nil (region-beginning) (region-end))))
))
;; I was surprised I needed this; perhaps a system restart will show I don't need it.
(add-hook 'org-capture-mode-hook #'my/setup-smart-paste)
#+end_src
Notes:
- You can use yank-media to do whatever you want with non-text selections in your clipboard. You can find an example of a function that attaches
files copied using a file manager to an org file.
- Modes that feel that they can do something useful with non-plain-text
selections can register themselves as such (and say which types they can
handle), and then there's a new ‘M-x yank-media' command the user can
use.
- Files and images can be attached by dropping onto Emacs
Attachment method other than ~org-attach-method~ for dropped files can
be specified using ~org-dnd-default-attach-method~.
Images dropped also respect the value of ~org-media-image-save-type~.
- Images and files in clipboard can be attached
Org can now attach images in clipboard and files copied/cut to the
clipboard from file managers using the ~yank-media~ command which also
inserts a link to the attached file.
Images can be saved to a separate directory instead of being attached,
customize ~org-media-image-save-type~.
- (org-setup-yank-dnd-handlers): Register yank-media-handler and DND (Drag-aNd-Drop) handler.
- (org-media-image-save-type, org-dnd-default-attach-method): New defcustoms.
- Add yank-media and DND handlers: (org--image-yank-media-handler, org--copied-files-yank-media-handler) (org--dnd-local-file-handler)
*** TODO C-c C-l Org-mode ⇐ HTML
:PROPERTIES:
:CUSTOM_ID: Org-mode-HTML
:END:
The following let's us copy htlm into org format using eww, Emacs' built-in web browser.
#+BEGIN_SRC emacs-lisp :tangle no
;; See: https://emacs.stackexchange.com/questions/7171/paste-html-into-org-mode
(use-package org-eww
:quelpa (org-eww :fetcher git :url "https://github.com/Fuco1/org-mode.git"))
#+END_SRC
It does not work as I'd like, but may prove useful to have around.
+ Possibly useful: Open a webpage with ~M-x eww~ then toggle ~M-x read-only-mode~ to
edit the text, say for notes or deletions, as you read! No need to copy-paste.
--------------------------------------------------------------------------------
[[https://github.com/alphapapa/org-web-tools][org-web-tools]] claims to /view, capture, and archive Web pages in Org-mode/; this
may be a very useful tool.
#+begin_src emacs-lisp
(use-package org-web-tools :defer t)
;; :config
;; Insert an Org-mode link to the URL in the clipboard or kill-ring. Downloads
;; the page to get the HTML title.
;; (bind-key* "C-c C-l" #'org-web-tools-insert-link-for-url) ;; Instead, see my/org-insert-link-dwim below.
#+end_src
Other useful functions, needing pandoc:
+ ~org-web-tools-insert-web-page-as-entry~ and
+ ~org-web-tools-convert-links-to-page-entries~.
#+begin_src emacs-lisp
;; C-u C-c C-l ⇒ Paste URL with title, WITHOUT prompting me for anything.
;; C-c C-l ⇒ Prompt me for title.
(bind-key* "C-c C-l"
(lambda () (interactive)
(call-interactively
(if current-prefix-arg
#'org-web-tools-insert-link-for-url
#'my/org-insert-link-dwim))))
;; From:
(defun my/org-insert-link-dwim ()
"Like `org-insert-link' but with personal dwim preferences.
- When text is selected, use that as the link description --and prompt for link type
- When a URL is in the clipboard, use that as the link type
- On an existing Org link, prompt to alter the link then to alter the description
- With a ‘C-u’ prefix, prompts for a file to link to.
- It is relative to the current directory; use ‘C-u C-u’ to get an absolute path.
It fallsback to `org-insert-link' when possible.
Functin Source: https://xenodium.com/emacs-dwim-do-what-i-mean/"
(interactive)
(let* ((point-in-link (org-in-regexp org-link-any-re 1))
(clipboard-url (when (string-match-p "^http" (current-kill 0))
(current-kill 0)))
(region-content (when (region-active-p)
(buffer-substring-no-properties (region-beginning)
(region-end)))))
(cond ((and region-content clipboard-url (not point-in-link))
(delete-region (region-beginning) (region-end))
(insert (org-make-link-string clipboard-url region-content)))
((and clipboard-url (not point-in-link))
(insert (org-make-link-string
clipboard-url
(read-string "title: "
(with-current-buffer (url-retrieve-synchronously clipboard-url)
(dom-text (car
(dom-by-tag (libxml-parse-html-region
(point-min)
(point-max))
'title))))))))
(t
(call-interactively 'org-insert-link)))))
#+end_src
*** When I “Smart Paste”, let's ensure things look nice!
**** Proportional fonts for Headlines
:PROPERTIES:
:CUSTOM_ID: Proportional-fonts-for-Headlines
:END:
Let's have headings stick out a bit.
+ The larger headings are cute and reminicint of word processors, but having
headings coloured is enough ---the larger size is too much.
#+BEGIN_SRC emacs-lisp
(set-face-attribute 'org-document-title nil :height 2.0)
;; (set-face-attribute 'org-level-1 nil :height 1.0)
;; Remaining org-level-𝒾 have default height 1.0, for 𝒾 : 1..8.
;;
;; E.g., reset org-level-1 to default.
;; (custom-set-faces '(org-level-1 nil))
#+END_SRC
Remember you can always use Emacs' Custom utility to get Lisp incantations ;-)
---See notes on Custom above.
**** Pretty Lists Markers
:PROPERTIES:
:CUSTOM_ID: Pretty-Lists-Markers
:END:
When writing, it's common to use ~+,-,*~ to enumerate unordered lists
---especially so in Org-mode wherein they denote structured text. Let's render
them visually as Unicode bullets.
#+begin_src emacs-lisp
;; (x y z) ≈ (existing-item replacement-item positivity-of-preceding-spaces)
(cl-loop for (x y z) in '(("+" "◦" "*")
("-" "•" "*")
("*" "⋆" "+"))
do (font-lock-add-keywords 'org-mode
`((,(format "^ %s\\([%s]\\) " z x)
(0 (prog1 () (compose-region (match-beginning 1) (match-end 1) ,y)))))))
#+end_src
**** Making Block Delimiters Less Intrusive
:PROPERTIES:
:CUSTOM_ID: Making-Block-Delimiters-Less-Intrusive
:END:
Let us render Org-mode's ~#+begin_src~ and ~#+end_src~ less obtrusively by,
e.g., having the former render as a pencil marker ~✎~ and the latter as a
tombstone ~□~ ---reminiscent of Halmos' QED end-of-proof marker.
# His setup also accounts for quotes.
#+begin_details Rasmus’ Incantation
This is from [[https://pank.eu/blog/pretty-babel-src-blocks.html#coderef-symbol][Rasmus Roulund]].
#+begin_src emacs-lisp
(defvar-local rasmus/org-at-src-begin -1
"Variable that holds whether last position was a ")
(defvar rasmus/ob-header-symbol ?☰
"Symbol used for babel headers")
(defun rasmus/org-prettify-src--update ()
(let ((case-fold-search t)
(re "^[ \t]*#\\+begin_src[ \t]+[^ \f\t\n\r\v]+[ \t]*")
found)
(save-excursion
(goto-char (point-min))
(while (re-search-forward re nil t)
(goto-char (match-end 0))
(let ((args (org-trim
(buffer-substring-no-properties (point)
(line-end-position)))))
(when (org-string-nw-p args)
(let ((new-cell (cons args rasmus/ob-header-symbol)))
(cl-pushnew new-cell prettify-symbols-alist :test #'equal)
(cl-pushnew new-cell found :test #'equal)))))
(setq prettify-symbols-alist
(cl-set-difference prettify-symbols-alist
(cl-set-difference
(cl-remove-if-not
(lambda (elm)
(eq (cdr elm) rasmus/ob-header-symbol))
prettify-symbols-alist)
found :test #'equal)))
;; Clean up old font-lock-keywords.
(font-lock-remove-keywords nil prettify-symbols--keywords)
(setq prettify-symbols--keywords (prettify-symbols--make-keywords))
(font-lock-add-keywords nil prettify-symbols--keywords)
(while (re-search-forward re nil t)
(font-lock-flush (line-beginning-position) (line-end-position))))))
(defun rasmus/org-prettify-src ()
"Hide src options via `prettify-symbols-mode'.
`prettify-symbols-mode' is used because it has uncollpasing. It's
may not be efficient."
(let* ((case-fold-search t)
(at-src-block (save-excursion
(beginning-of-line)
(looking-at "^[ \t]*#\\+begin_src[ \t]+[^ \f\t\n\r\v]+[ \t]*"))))
;; Test if we moved out of a block.
(when (or (and rasmus/org-at-src-begin
(not at-src-block))
;; File was just opened.
(eq rasmus/org-at-src-begin -1))
(rasmus/org-prettify-src--update))
;; Remove composition if at line; doesn't work properly.
;; (when at-src-block
;; (with-silent-modifications
;; (remove-text-properties (match-end 0)
;; (1+ (line-end-position))
;; '(composition))))
(setq rasmus/org-at-src-begin at-src-block)))
(defun rasmus/org-prettify-symbols ()
(mapc (apply-partially 'add-to-list 'prettify-symbols-alist)
(cl-reduce 'append
(mapcar (lambda (x) (list x (cons (upcase (car x)) (cdr x))))
`(("#+begin_src" . ?✎) ;; ➤ 🖝 ➟ ➤ ✎
("#+end_src" . ?□) ;; ⏹
("#+header:" . ,rasmus/ob-header-symbol)
("#+begin_quote" . ?»)
("#+end_quote" . ?«)))))
(turn-on-prettify-symbols-mode)
(add-hook 'post-command-hook 'rasmus/org-prettify-src t t))
;; Last updated: 2019-06-09
#+end_src
#+end_details
#+BEGIN_SRC emacs-lisp
(add-hook 'org-mode-hook #'rasmus/org-prettify-symbols)
;; Note: org-mode-restart only works in org buffers, not at init time
#+END_SRC
His development relies on built-in prettify-symbols-mode, which
disguises strings in a buffer for the sake of readability or
aesthetics. Following the example in the documentation, ~C-h f
prettify-symbols-mode~, we can quickly approximate his efforts for
~example~ blocks as follows, however a main issue is that source blocks
have busybodied headers which his setup disguises as ‘≡’.
#+begin_src emacs-lisp
(global-prettify-symbols-mode)
(defvar my/prettify-alist nil
"Musa's personal prettifications.")
(cl-loop for pair in '(;; Example of how pairs like this to beautify org block delimiters
("#+begin_example" . (?ℰ (Br . Bl) ?⇒)) ;; ℰ⇒
("#+end_example" . ?⇐) ;; ⇐
;; Actuall beautifications
("==" . ?≈) ("===" . ?≈) ;; ("=" . ?≔) ;; Programming specific prettifications
("i32" . ?ℤ) ("u32" . ?ℕ) ("f64" . ?ℝ) ;; Rust specific
("bool" . ?𝔹)
;; ("\"\"\"\n" . ?“) ("\"\"\"" . ?”)
("\"\"\"" . ?“)
("fn" . ?λ)
("<=" . ?≤) (">=" . ?≥)
("->" . ?→) ("-->". ?⟶) ;; threading operators
("[ ]" . ?□) ("[X]" . ?☑) ("[-]" . ?◐)) ;; Org checkbox symbols
do (push pair my/prettify-alist))
;; Replace all Org [metadata]keywords with the “▷” symbol; e.g., “#+title: Hello” looks like “▷ Hello”.
(cl-loop for keyword in '(title author email date description options property startup export_file_name html_head fileimage filetags)
do (push (cons (format "#+%s:" keyword) ?▷) my/prettify-alist))
(cl-loop for hk in '(text-mode-hook prog-mode-hook org-mode-hook)
do (add-hook hk (lambda ()
(setq prettify-symbols-alist
(append my/prettify-alist prettify-symbols-alist)))))
(add-hook 'org-mode-hook (lambda () (push '("# " . (?🎶 (Br . Bl) ?\ )) prettify-symbols-alist)))
#+end_src
For more on prettify-symbols-mode, read the informative [[https://tony-zorman.com/posts/pretty-latex.html][Prettifying LaTeX Buffers]].
#+RESULTS:
:Did_it_work:
#+begin_example lisp
(<= (+ 1 1) (--> 2))
1 =
2 ==
3 ===
#+end_example
:End:
See [[http://www.modernemacs.com/post/prettify-mode/][“Mathematical Notation in Emacs”]] for how such prettifications can
make verbose (Python) scripts much more readable by employing more
economical disguises.
A nice sanity:
#+BEGIN_SRC emacs-lisp
;; Un-disguise a symbol when cursour is inside it or at the right-edge of it.
(setq prettify-symbols-unprettify-at-point 'right-edge)
#+END_SRC
**** Hiding Emphasis Markers, Inlining Images, and LaTeX-as-PNG
:PROPERTIES:
:CUSTOM_ID: Hiding-Emphasise-Markers-Inlining-Images-and-LaTeX-as-PNG
:END:
:yay_it_worked:
$e^x = \sum_{n = 0}^\infty \frac{x^n}{n!}$
~awkward~ or $not$
:end:
Let's make some things prettier than they appear by default.
#+BEGIN_SRC emacs-lisp
;; org-mode math is now highlighted ;-)
(setq org-highlight-latex-and-related '(latex))
;; Extra space between text and underline line
(setq x-underline-at-descent-line t)
;; Hide the *,=,/ markers
(setq org-hide-emphasis-markers t)
;; Let’s limit the width of images inlined in org buffers to 400px.
(setq org-image-actual-width 400)
;; Visually, I prefer to hide the markers of macros, so let’s do that:
;; {{{go(here)}}} is shown in Emacs as go(here)
(setq org-hide-macro-markers t)
;; On HTML exports, Org-mode tries to include a validation link for the exported HTML. Let’s disable that since I never use it.
;; (setq org-html-validation-link nil)
;; Musa: This is super annoying, in practice.
(setq org-pretty-entities nil) ;; Also makes subscripts (x_{sub script}) and superscripts (x^{super script}) appear in org in a WYSIWYG fashion.
;; to have \alpha, \to and others display as utf8
;; http://orgmode.org/manual/Special-symbols.html
;;
;; Be default, any consectuive string after “_” or “^” will be shown in WYSIWYG fashion; the following requires “^{⋯}” instead.
;; (setq org-use-sub-superscripts (quote {}))
#+END_SRC
Org pretty entities seems rather impressive ---=M-x org-entities-help= to see all
possibilities, or add your own. I'm already using the Agda input method, so I
wont use Org's ---Agda's gives me a tiny menu narrowing possibilities as I type.
However, it does make subscripts (x_{sub script}) and superscripts (x^{super script}) appear in Org in a WYSIWYG fashion.
--------------------------------------------------------------------------------
Automatically display emphasis markers and links when the cursor is on them.
(c.f. ~fragtog~ below)
#+begin_src emacs-lisp
(use-package org-appear
:hook org-mode
:custom ((org-appear-autoemphasis t)
(org-appear-autolinks nil)
(org-appear-autosubmarkers nil)))
#+end_src
--------------------------------------------------------------------------------
The following is now disabled (yet again, as of Dec/31/2020) ---it makes my system slower than I'd like.
#+BEGIN_SRC emacs-lisp :tangle no
;; Show inline images when loading a new Org file.
(setq org-startup-with-inline-images t)
;; Whenever a src block is run, redisplay images so they're up-to-date.
;; Very useful when using ‘ob-latex-as-png’, below.
(add-hook 'org-babel-after-execute-hook #'org-redisplay-inline-images)
;; Automatically convert LaTeX fragments to inline images.
(setq org-startup-with-latex-preview t)
#+END_SRC
--------------------------------------------------------------------------------
# latex-preview-in-org
Org mode supports inline image previews of LaTeX fragments; e.g., $e^{i \cdot
\pi} - 1 = 0$ or $\substack{𝔹 \\ ↓ \\ 𝒜}$. These can be toggled with
kbd:C-c_C-x_C-l. [[https://github.com/io12/org-fragtog][Org-fragtog]] automates this, so fragment previews are disabled
for editing when your cursor steps onto them, and re-enabled when the cursor
leaves.
#+BEGIN_SRC emacs-lisp
;; Automatically toggle LaTeX previews when cursour enters/leaves them
(use-package org-fragtog
:disabled t
:hook (org-mode . org-fragtog-mode))
#+END_SRC
doc:org-latex-preview, kbd:C-c_C-x_C-l, renders ~$e^{i \pi} + 1 = 0$~ into a
really nice inline image: $e^{i \pi} + 1 = 0$. It also works for LaTeX
environments ---for personal environments, just ~(add-to-list
'org-latex-packages-alist "LaTeX definitions here")~.
[Disabled]
#+begin_src emacs-lisp :tangle no
;; Make previews a bit larger
(setq org-format-latex-options (plist-put org-format-latex-options :scale 1.5))
;; I use a lot of Unicode, so let's always include a unicode header.
(maybe-clone "https://armkeh.github.io/unicode-sty/")
(setq org-format-latex-header
(concat org-format-latex-header
"\n\\usepackage{\\string~\"/unicode-sty/unicode\"}"))
;;
;; Now this looks nice too!
;; $\substack{𝔹 \\ ↓ \\ 𝒜}$ and $\mathbb{B}$.
;; Always support unicode upon LaTeX export
;; No need to explicitly import armkeh's unicode-sty in each org file.
(add-to-list 'org-latex-packages-alist
"\n\\usepackage{\\string~\"/unicode-sty/unicode\"}")
#+end_src
This approach does not work well for forming diagrams; I've tried to make tikzcd
work this way and failed. Using ~ob-latex-as-png~ as a substitute.
# work this way and failed. Using [doc : org-babel-execute:latex-as-png][ob-latex-as-png] as a substitute.
:calc:
#+begin_src emacs-lisp :tangle no
;; \step should be local to \begin{calc}⋯\end{calc}!
(add-to-list 'org-latex-packages-alist
"\\def\\BEGINstep{ \\{ }
\\def\\ENDstep{ \\} }
\\newcommand{\\step}[2][=]{ \\\\ #1 \\;\\; & \\qquad \\color{maroon}{\\BEGINstep \\text{ #2 } \\ENDstep} \\\\ & }
\\newenvironment{calc}{\\begin{align*} & }{\\end{align*}}")
; (pop org-latex-packages-alist)
;; See also org-format-latex-header
#+end_src
:End:
# LaTeX Rendering: Support “latex-as-png” src blocks, which show LaTeX as PNGs
# LaTeX-Rendering-Support-latex-as-png-src-blocks-which-show-LaTeX-as-PNGs
#+BEGIN_SRC emacs-lisp
;; Support “latex-as-png” src blocks, which show LaTeX as PNGs
(use-package ob-latex-as-png :disabled t)
#+END_SRC
--------------------------------------------------------------------------------
Use ~ref:my-stuff~ to refer to an Org entity with ~#+name: my-stuff~; which must
have a ~#+caption: ⋯~ as well. Example entities include tables and source
blocks; as well as figure blocks. For equation blocks, you must use a
~\label{⋯}~ directly.
#+begin_src emacs-lisp
;; Use the “#+name” the user provides, instead of generating label identifiers.
(setq org-latex-prefer-user-labels t)
#+end_src
**** Org-Emphasise for Parts of Words :Disabled:
:PROPERTIES:
:CUSTOM_ID: Org-Emphasise-for-Parts-of-Words
:header-args: :tangle no
:END:
From [[https://stackoverflow.com/a/24540651/3550444][stackoverflow]], the following incantation allows us to have
parts of works emphasied with org-mode; e.g.,
/half/ed, ~half~ed, and right in the m*idd*le! Super cool stuff!
#+BEGIN_SRC emacs-lisp :tangle no
(setcar org-emphasis-regexp-components " \t('\"{[:alpha:]")
(setcar (nthcdr 1 org-emphasis-regexp-components) "[:alpha:]- \t.,:!?;'\")}\\")
(org-set-emph-re 'org-emphasis-regexp-components org-emphasis-regexp-components)
#+END_SRC
I've disabled this feature since multiple occurrences
of an emphasise marker are sometimes treated as one
lengthy phrase being emphasised.
**** Now C-c C-x C-v shows remote images inline, neato!
#+begin_src emacs-lisp :tangle init.el
(use-package org-remoteimg
:vc (:url "https://github.com/gaoDean/org-remoteimg")
:custom ((url-cache-directory "~/emacs.d/.cache/")
(url-automatic-caching t)
(org-display-remote-inline-images 'cache)))
#+end_src
Example:
[[https://www.javacodegeeks.com/wp-content/uploads/2017/09/lexer-parser-center.png][lexing vs parsing]]
[[https://miro.medium.com/v2/resize:fit:4800/1*bpG6TxN-nS6enHkp-KIZgg.jpeg][1% better everyday, push-ups!]]
**** Draw pretty unicode tables in org-mode
:PROPERTIES:
:CUSTOM_ID: Draw-pretty-unicode-tables-in-org-mode
:END:
This turns the “---” and other ASCII for tables into ‘smooth’ lines ^_^
|---+---|
| a | b |
|---+---|
| 1 | 2 |
|---+---|
| | |
|---+---|
#+begin_src emacs-lisp
(use-package org-pretty-table
:vc (:url "https://github.com/Fuco1/org-pretty-table")
:hook org-mode)
#+END_SRC
Being an ‘on the fly replacement mechanism’, we get that “C-u 80 -” also results
in one smooth horizontal rule and vertical sequences of ‘|’ results in a smooth
vertical line.
NOTE. This is comparable to ~org-modern-mode~'s pretty table rendering.
**** Use backtick as an alternative to “~” for code font
:PROPERTIES:
:CREATED: [2025-04-09 Wed 16:40]
:RELATED: https://protesilaos.com/codelog/2022-01-05-custom-face-org-emphasis-alist/
:FOR_HTML_EXPORT_SUPPORT: https://www.gonsie.com/blorg/org-highlight.html
:END:
#+begin_src emacs-lisp
;; Working with others: `This is a piece of code`
(add-hook 'org-font-lock-set-keywords-hook
(defun my/backticks-denote-code ()
(add-to-list 'org-font-lock-extra-keywords
'("\\(`\\)\\(.*\\)\\(`\\)"
(1 '(face nil invisible t))
(3 '(face nil invisible t))
;; (2 '(face code))
(2 '(:box t :foreground "#AAF"))))))
#+end_src
** [Conversely,] Rich Copy Commands :: =my/copy-as-{jira, slack, reddit, confluence}=
:PROPERTIES:
:CREATED: [2025-01-20 Mon 11:27]
:END:
Authoring pretty comments (with colourful code blocks) in Jira can be done
easily by composing them in Org mode, then invoking ~my/copy-as-jira~.
#+begin_src emacs-lisp
(cl-defun my/copy-as-jira ()
"Export region to Jira markdown, and copy to the kill ring for pasting into other programs."
(interactive)
(use-package ox-jira)
(message "Converting to Jira Markdown...")
(kill-new (org-export-as 'jira))
(message "Copied as Jira Markdown!"))
(cl-defun my/copy-as-reddit ()
"Export region to Reddit (i.e., Github Flavoured Markdown), and copy to the kill ring for pasting into other programs.
“Mode for Reddit”: Conversely, to read Reddit within Emacs,
(use-package md4rd :config (setq md4rd-subs-active '(emacs clojure shia)))
then “M-x md4rd”."
(interactive)
(use-package ox-gfm)
(message "Converting to Reddit Markdown...")
(kill-new (org-export-as 'gfm))
(message "Copied as Reddit Markdown!"))
(cl-defun my/copy-as-slack ()
"Export region to slack, and copy to the kill ring for pasting into other programs."
(interactive)
(use-package ox-slack)
(message "Converting to Slack Markdown...")
(kill-new (org-export-as 'slack nil nil :body-only-please))
(message "Copied as Slack Markdown! In Slack press “⌘ Shift F” to apply the formatting."))
;;
;; For links to display nicely, I need this code:
;; https://github.com/titaniumbones/ox-slack/pull/9
(defun org-slack-link (link contents info)
"Transcode LINK object into Markdown format.
CONTENTS is the link's description. INFO is a plist used as
a communication channel."
(let ((link-org-files-as-md
(lambda (raw-path)
;; Treat links to `file.org' as links to `file.md'.
(if (string= ".org" (downcase (file-name-extension raw-path ".")))
(concat (file-name-sans-extension raw-path) ".md")
raw-path)))
(type (org-element-property :type link)))
(cond
;; Link type is handled by a special function.
((org-export-custom-protocol-maybe link contents 'md))
((member type '("custom-id" "id" "fuzzy"))
(let ((destination (if (string= type "fuzzy")
(org-export-resolve-fuzzy-link link info)
(org-export-resolve-id-link link info))))
(pcase (org-element-type destination)
(`plain-text ; External file.
(let ((path (funcall link-org-files-as-md destination)))
(if (not contents) (format "%s>" path)
(format "[%s](%s)" contents path))))
(`headline
(format
;; "[%s](#%s)"
"[%s]"
;; Description.
(cond ((org-string-nw-p contents))
((org-export-numbered-headline-p destination info)
(mapconcat #'number-to-string
(org-export-get-headline-number destination info)
"."))
(t (org-export-data (org-element-property :title destination)
info)))
;; Reference.
;; (or (org-element-property :CUSTOM_ID destination)
;; (org-export-get-reference destination info))
))
(_
(let ((description
(or (org-string-nw-p contents)
(let ((number (org-export-get-ordinal destination info)))
(cond
((not number) nil)
((atom number) (number-to-string number))
(t (mapconcat #'number-to-string number ".")))))))
(when description
(format "[%s]"
description
;; (org-export-get-reference destination info)
)))))))
((org-export-inline-image-p link org-html-inline-image-rules)
(let ((path (let ((raw-path (org-element-property :path link)))
(cond ((not (equal "file" type)) (concat type ":" raw-path))
((not (file-name-absolute-p raw-path)) raw-path)
(t (expand-file-name raw-path)))))
(caption (org-export-data
(org-export-get-caption
(org-export-get-parent-element link)) info)))
(format ""
(if (not (org-string-nw-p caption)) path
(format "%s \"%s\"" path caption)))))
((string= type "coderef")
(let ((ref (org-element-property :path link)))
(format (org-export-get-coderef-format ref contents)
(org-export-resolve-coderef ref info))))
((equal type "radio") contents)
(t (let* ((raw-path (org-element-property :path link))
(path
(cond
((member type '("http" "https" "ftp" "mailto"))
(concat type ":" raw-path))
((string= type "file")
(org-export-file-uri (funcall link-org-files-as-md raw-path)))
(t raw-path))))
(if (not contents) (format "%s" path)
(format "[%s](%s)" contents path)))))))
(cl-defun my/copy-as-confluence ()
"Export region to Confluence, and copy to the kill ring for pasting into other programs.
More precisely, export the selected region to HTML and copy it to the clipboard.
Note: Confluence has no markup language, it's a WYSIWYG editor,
but it does recognise formatted text, such as what you copy off a webpage."
(interactive)
(message "Converting to Confluence Markdown...")
;; NOTE: Consider using https://git.sr.ht/~bzg/org-contrib/blob/master/lisp/ox-confluence.el
(kill-new (org-export-as 'html))
(message "Copied as Confluence Markdown!"))
#+end_src
Note: There is a package [[https://github.com/sshaw/copy-as-format][copy-as-format]] which is an “Emacs function to copy
buffer locations as GitHub/Slack/JIRA etc... *formatted code*.” That is, it takes
my region [[https://github.com/sshaw/copy-as-format/blob/master/copy-as-format.el#L208][and wraps it in ```]], more-or-less. 😦 Not terribly useful.
Finally, there is the package [[https://github.com/etern/edit-as-format][edit-as-format]]: It will allow me to edit, say, a
markdown file using Org syntax 😻
** Attachments: Making external files into TODOs or Reference Matter :ATTACH:
:PROPERTIES:
:CREATED: [2025-04-27 Sun 05:37]
:ID: 0F813D85-5001-4AF7-A6C8-A3FFB84409A3
:END:
:LOGBOOK:
CLOCK: [2025-04-27 Sun 08:45]--[2025-04-28 Mon 10:27] => 25:42
CLOCK: [2025-04-27 Sun 08:13]--[2025-04-27 Sun 08:15] => 0:02
:END:
I simply take my notes about various activities or projects. When I do something involved, I take notes in a heading,
add tags to it, and attach relevant files (like document scans or git repos or book/article pdfs). Later, I can recall
the activity by tags/text and examine the attachments while refreshing the context reading the notes. As such, file
search is improved since I have access to a combination of date of creation, topic tags, and comments.
Org mode lets me mix my tasks with my notes, and ~org-attach~ lets me embed my files right into my notes (i.e.,
contextually: Files are attached to the node to which their content pertains), so that I don't have to even think about
file-naming conventions and folder directory hierarchies myself. After all, files are always associated with some note
or task. Finding files becomes super simple: Do a test search on my Org file for any related descriptive term.
Importantly, organising your files this way leverages the full power of the org-mode organisational system. E.g., need
to do some action with the related files at some point? Create a (scheduled) =TODO=. Want to add meta-data to a file?
Create a property.
+ I use org-attach to simply attach to the relevant node accordingly. Every file is then where it should be based on its
conceptual context, rather than its filesystem hierarchy. No more worrying about filename or directory naming. It's
simply attached to the descriptive node making it clear what precisely it is and under what context it is
meaningful. I am then easily able to open it from there.
It's often useful to associate reference material---text, files, or folders---with outline nodes. Small notes can live
in subtrees, while files and external material can be linked via hyperlinks or managed through the powerful =org-attach=
system.
*Key Points about =org-attach=:*
- *Storage Model:* Files are attached to Org headings, typically organized using an =ID=-based directory under a =data/=
folder near the Org file.
- *Automation:* Attachments automatically add an =ATTACH= tag to the heading, and links are easy to insert and use anywhere
in the subtree. ~C-c C-a~ to add an attachment, then ~C-c C-l~ to insert a link to it.
- There is no decision needed for folder-name or location.
# - Attachments are inherited: If a section has an attachment, then a link to it can occur anywhere in that section,
# including any sub-sections.
- *Git Integration:* You can commit attachment changes automatically via =org-attach-git=.
*Benefits:*
- Files become part of your notes, independent of filesystem hierarchies.
- Attachments support rich metadata: tags, notes, scheduling, TODO states.
- Searching becomes intuitive: context and tags replace navigating folders.
- The filesystem becomes a hidden implementation detail, letting you think and organize contextually, not structurally.
*Practical Usage:*
- Attach files with =C-c C-a a=, or save an entire buffer with =C-c C-a b= as a file in the attachment directory.
- You can attach entire directories too, just as easily as files.
- Files like PDFs, reviews, documents, and even Git repositories can be integrated seamlessly into your Org workflow.
- Use tools like =helm-org-ql= or =helm-org-rifle= to rapidly find attached files via contextual search.
*Motivation:* This approach transforms isolated files into actionable, contextual knowledge objects. Instead of managing
folders and filenames manually, I manage ideas, tasks, and references directly within their Org files. Once my files
are all in Org attachments, I can use =helm-org-ql= to search them easily (and quickly). Each headline associated with a
file (or collection of files, like Git repo) can be assigned notes, todo-state, tags, or be scheduled. That is,
~org-attach~ allows me to turn ‘files’ into ‘org headlines’! E.g., either as TODOs or as Reference matter, either way
files become part of my-life.org and I can “progress” on them or see them when looking up reference matter. 💝
- E.g., sometimes I have open PDFs that I'd like to get around to reading, but now I can just attach the PDF to an Org
headline, schedule it, and make progress on finishing the PDF.
- I get annual performance reviews, as PDF, so I attach them to a ~* Performance Review~ headline so that I can consult
them when it's review time.
- Note: I can just drag-and-drop the files, but often I just do ~C-c C-a a~ then select a file (or directory!) to have it
attached, then press ~C-c C-l~ to paste an Org link to the attachment.
+ I run =M-x org-lint= to mitigate [[https://en.wikipedia.org/wiki/Link_rot][link rot]] and ensures that when I do bulk find-replace actions that I haven't royally
messed things up.
Incidentally, Org-attach solves a few problems:
1. “Where do I keep a file related to my notes?” ⇒ Right /inside/ your notes! (The filesystem is an implementation
detail!)
+ Org-attach means I can have my files /independent/ of any file/folder hierarchy, and can find them
contextually. E.g., use ~M-x helm-org-rifle :ATTACH: any related phrases here~ to quickly look for Org headlines with
attachments that match any of my search phrases.
2. “Should I have a folder hierarchy that matches by Org headlines hierarchy?” ⇒ No, folders are an implementation
detail, only worry about your Org headlines.
3. “Now, I'm too afraid to move a file since it might break Org links to it!” ⇒ Use ~M-x org-lint~ to ensure there's no
link rot, and there's no need to move files since the file system is an implementation detail!
4. “How do I add notes to a file? Or tags?” ⇒ Easy! Since your file is not part of an Org heading, just use usual Org
tags to tag the heading and add notes in that heading, and even schedule the file (i.e., the Org heading for review).
Then, for example, ~M-x helm-org-ql tags:ATTACH,otherTagHere some context phrases here~ the first =ATTACH= part only
considers headlines with attachments (i.e., your files), then ~otherTagHere~ is any other tag you might have used for
your file/notes, and finally the remaining phrases do a search for the notes associated with your file.
+ As such, org-attach is more expressive than a bare file system.
Ironically, besides =my-life.org=, I don't have much other files these days, besides the occasional PDF for work or an
image scan of some policy. (In contrast, if I were to be a lecturer again, then I might have headlines pertaining to
individual classes which would have subheadings for individual students and those would have attachments to their work).
Finally, when doing my weekly review, I clean out my =~/Downloads= and =~/Desktop= and ~/emacs.d/ directories and anything
there that might be useful is attached to a (possibly new) Org headline.
TODO, Low priority: Configure org-babel to produce output files in the attachment dirs of the heading it is ran in.
*** my/dired-copy-image-to-clipboard
:PROPERTIES:
:CREATED: [2025-04-28 Mon 20:25]
:END:
#+begin_src emacs-lisp
(defun my/dired-copy-image-to-clipboard ()
"Copy the currently selected image file in dired to the clipboard as image data, so that I can paste it with ⌘-v into Slack or other programs.
Note,
1. In dired, “C-u 0 w” copies the absolute file path at point.
2. In MacOS finder, press “⌘+Shift+g” and type in or paste a path.
(Equivalently, in Finder look at the “Go” menu bar item, then select “Go to folder”.)
"
(interactive)
(let* ((file (dired-get-file-for-visit))
(escaped-file (replace-regexp-in-string "\"" "\\\\\"" file))
(script (format "osascript -e 'set the clipboard to (read (POSIX file \"%s\") as {«class PNGf»})'" escaped-file)))
(if (and (file-exists-p file)
(string-match-p (image-file-name-regexp) file))
(progn
(shell-command script)
(message "Copied image to clipboard: %s" file))
(message "Not an image file: %s" file))))
#+end_src
*** [#C] [Super Low Priority] Orphaned attachments --Part of the Weekly Review
:PROPERTIES:
:CREATED: [2025-04-27 Sun 07:00]
:END:
How to delete unused org-mode attachment files from disc
In org-mode, after deleting a lot of headlines that have had attachment files,
the unrefereced files now remain on the disc in my data subdirectory.
Is there a function or script that finds all unrefereced files and does a cleanup?
TODO: This code erroneously assumes any unmentioned attachment is an
orphan! But really, an orphan is an attachment whose parent UUID directory is
not the UUID of an ~:ID:~ property of some Org headline.
#+begin_src emacs-lisp
(defun my/find-orphaned-attachments ()
"Shows buffer of clickable “Orphaned Attachment ❓ Verify unused ❌ Delete” rows.
Check for orphaned files in the Org attachment directory.
NOTE: This implemention assumes all of my attachements are uniquely named,
which is not necessairly true! As such, I've added a ‘verify’ button.
"
(interactive)
(when (derived-mode-p 'org-mode)
(let* ((attach-dir (or (org-attach-dir) ;; try entry-specific attach dir
(when (boundp 'org-attach-id-dir) org-attach-id-dir)
(expand-file-name "data/" (file-name-directory (buffer-file-name))))) ;; fallback default
(all-attachments (when (file-directory-p attach-dir)
(directory-files-recursively attach-dir ".*" nil)))
;; Collect all attachment links in all Org files
(linked-attachments (-flatten (loop for org-file in (directory-files-recursively default-directory "\\.org$")
unless (or (s-contains-p ".emacs.d/elpa" org-file) (s-contains-p ".emacs.d/quelpa" org-file))
collect (with-temp-buffer
(insert-file-contents org-file)
(org-mode)
(org-element-map (org-element-parse-buffer) 'link
(lambda (link)
(when (string= (org-element-property :type link) "attachment")
(org-element-property :path link))))))))
;; Now check for unreferenced files
(results (loop for attachment in all-attachments
for att = (f-base attachment)
unless (member att (--map (f-base it) linked-attachments))
collect (format "- [[file:%s][%s]] ❓ [[elisp:(rgrep \"%s\" \"*.org\")][Verify unused]] ❌ [[elisp:(progn (ignore-errors (f-delete \"%s\")) (kill-whole-line))][Delete!]]"
attachment att att (concat default-directory attachment)))))
;; Create and display a new buffer
(with-current-buffer (get-buffer-create "*Orphaned Attachments*")
(erase-buffer)
(insert (string-join results "\n"))
(org-mode)
(goto-char (point-min))
(pop-to-buffer (current-buffer))))))
#+end_src
*** Powerful Directory Editing with ~dired :Disabled:~
:PROPERTIES:
:CUSTOM_ID: Powerful-Directory-Editing-with-dired
:header-args: :tangle no
:END:
⟨ ~C-x d~ to open a file or directory in dired, using the current buffer. ⟩
As mentioned earlier, ~dired~ is Emacs' built-in directory editor; it's opened
with ~C-x d~. /Dired let's us treat directories as textual objects!/ In dired,
press ~h~ to see the many actions available. Here's a few...
#+begin_details Super Terse ‘dired’ Tutorial
+ ~(~ toggles hiding entry details, such as modification date and ownership
+ ~s~ sort entries; modeline will display “Dired by date” or “Dired by name”.
+ ~o~ to open entry in anOther window; or ~RET~ to open in place.
+ ~+~ to create a new directory; or ~M-x make-directory~.
+ ~/~ to filter entries; with ~which-key~, possible completions pop-up.
- E.g., ~/ f~ shows only files or ~/ . png~ to obtain all entries with extension
~png~.
- ~/ i g~ to hide git-ignored items ^_^
- ~/ /~ to remove all filters.
+ ~TAB~ to navigate between different groupings of entries.
- ~RET~ on a drawer heading toggles folding it ^_^
#+end_details
The [[https://github.com/Fuco1/dired-hacks#dired-hacks-utils][dired-hacks]] family of packages lets us, say, get a dired buffer out of a shell
incantation that lists files, or use dired to open files with external tools.
Below we use three of its packages.
Pressing ~i~ inserts a directory's children under it, indented, in the current
buffer. Useful to see what's there.
#+BEGIN_SRC emacs-lisp
(use-package dired-subtree
:bind (:map dired-mode-map
("i" . dired-subtree-toggle)))
#+END_SRC
When directory ~𝒳~ has only one child ~𝒴~, then in dired, instead of ~𝒳~, show me ~𝒳/𝒴~
with ~𝒳~ greyed out.
#+BEGIN_SRC emacs-lisp
(use-package dired-collapse
:hook (dired-mode . dired-collapse-mode))
#+END_SRC
Begin dired with certain entries grouped together, according to some filtering
requirement; and with “garbage” files not shown ---i.e., those ending in
~.aux, .out~, etc.
#+BEGIN_SRC emacs-lisp
(use-package dired-filter
:hook (dired-mode . (lambda () (dired-filter-group-mode)
(dired-filter-by-garbage)))
:custom
(dired-garbage-files-regexp
"\\(?:\\.\\(?:aux\\|bak\\|dvi\\|log\\|orig\\|rej\\|toc\\|out\\)\\)\\'")
(dired-filter-group-saved-groups
'(("default"
("Org" (extension "org"))
("Executables" (exexutable))
("Directories" (directory))
("PDF" (extension "pdf"))
("LaTeX" (extension "tex" "bib"))
("Images" (extension "png"))
("Code" (extension "hs" "agda" "lagda"))
("Archives"(extension "zip" "rar" "gz" "bz2" "tar"))))))
#+END_SRC
#+begin_details [Disabled] Neotree: Traditional Directory Tree Navigation
link-here:Neotree-Traditional-Directory-Tree-Navigation
We open a nifty file manager upon startup.
#+BEGIN_SRC emacs-lisp :tangle no
;; Sidebar for project file navigation
(use-package neotree
:disabled
:config (global-set-key "\C-x\ d" 'neotree-toggle)
(setq neo-theme 'icons)) ;; Uses all-the-icons from § Booting Up
;; Open it up upon startup.
;; (neotree-toggle)
#+END_SRC
By default ~C-x d~ invokes ~dired~, but I prefer ~neotree~ for file
management.
⟨ Edit: As a naive user, this is what I thought; yet a year later,
I've almost never used neotree. ⟩
Useful navigational commands include
+ ~U~ to go up a directory.
+ ~C-c C-c~ to change directory focus; ~C-C c~ to type the directory out.
+ ~?~ or ~h~ to get help and ~q~ to quit.
As always, to go to the neotree pane when it's the only other window,
execute ~C-x o~.
I /rarely/ make use of this feature; auto-complete (via company mode & Helm
together) quickly provide an automatic replacement for nearly all of my uses.
+ Reminiscent of GUI file managers is [[https://github.com/ralesi/ranger.el#features][ranger]]; e.g., it has multi-column
display of parent directories along with a file preview mechanism.
#+end_details
** Org-rifle
:PROPERTIES:
:CREATED: [2025-04-27 Sun 06:26]
:END:
It searches both headings and contents of entries in Org buffers, and it
displays entries that match all search terms, whether the terms appear
in the heading, the contents, or both. Matching portions of entries'
contents are displayed with surrounding context and grouped by buffer to
make it easy to acquire your target.
;;
In contrast with =org-occur= and similar commands, =helm-org-rifle= is
entry-based (i.e. a heading and all of its contents, not including
subheadings), while =org-occur= is line-based. So =org-occur= will show
you entire lines that contain matching words, without any reference to
the heading the line is under, while =helm-org-rifle= will show the
heading of the entry that matches, followed by context around each
matching word in the entry. In other words, =helm-org-rifle= is sort of
like Google, while =org-occur= is sort of like =grep=.
;;
;; 😲 Select multiple results with ~C-SPC~ to display them together in a read-only
buffer. 💝 Or, just press ~C-s~ to see all results together in such a buffer.
;;
;; Tip: Use a word like “TODO, DONE, #A, :MyTag:” in your search to find TODO/DONE/priority-A/:MyTag: tasks．
;; Negate matches with “!”; e.g., “pizza !mushrooms”.
#+begin_src emacs-lisp
;; M-x helm-org-rifle ⇒ Search all open Org files, results are shown with
;; /context/, not just line-based. ⚠️ This respects narrowing.
(use-package helm-org-rifle :defer t)
#+end_src
This is a nice complement to helm-org-ql in that it shows me context while I'm searching.
** Mitigate accidental deletion of large regions of text
#+begin_src emacs-lisp
;; Note: TAB on a heading is great to cycle, but when there's lots of text /before/ subheadings,
;; it can be hard to see the outline. Instead on a heading press “C-c C-k” to ‘kill’ (i.e., hide!) such
;; notes and only show the outline. Very nice.
(setq org-ctrl-k-protect-subtree :please-ask-me-when-deleting-a-collapsed-subtree-with-C-k)
;; When an org heading is folded and I press “C-k”, then only operate on the headline, not the contents!
;; Pressing “C-k” deletes tags iff cursour is at the end of the headline text and before tags.
(setq org-special-ctrl-k :please-make-C-k-consider-headline-and-tags-only)
;; Likewise the “k” speed key should also confirm before doing anything.
(map-put org-speed-commands "k" nil) ;; Orginally: org-cut-subtree
;; For any key press, the DELETE key, M-S-RET for creation of new headings, etc.
;; Note “being next to an invisible region” means cursor is immediately *after* such a region or immediately *before*.
;; As such, if you press M-DELETE at the end of the line of a folded heading, it's considered an invisible edit.
;; However, if you press M-DELETE at the start of the line *after* a folded heading, it's not considered an invisible edit! 😲
;; Instead you end-up deleting some invisible text! This is because of how the method org-fold-check-before-invisible-edit is defined.
(setq org-catch-invisible-edits 'show-and-error)
;; Require confirmation for large region deletion
(😴 -let [wimpy-del.el "~/.emacs.d/elpa/wimpy-del.el"]
(unless (f-exists? wimpy-del.el)
(url-copy-file "https://www.emacswiki.org/emacs/download/wimpy-del.el" wimpy-del.el))
(load-file wimpy-del.el)
(setq wimpy-delete-size 3000)
(bind-key* "C-w" #'kill-region-wimpy))
;; Note: This has no impact if you select a region, then just press DELETE. Let's fix that:
;;
(defun my/confirm-big-deletion (orig-fun &rest args)
"Ask for confirmation if deleting more than `wimpy-delete-size' characters in `org-delete-backward-char`."
;; If deletion should not be done, show wimpy msg, otherwise do the deletion.
(if (and (region-active-p)
(-let [size (- (region-end) (region-beginning))]
(and (> size wimpy-delete-size) (not (yes-or-no-p (format "Really delete %d characters? " size))))))
(message wimpy-delete-dopey-message)
(apply orig-fun args)))
;;
(advice-add 'org-delete-backward-char :around #'my/confirm-big-deletion) ;; For Org-mode
(advice-add 'backward-delete-char-untabify :around #'my/confirm-big-deletion) ;; For everywhere else
#+end_src
** Prose
:PROPERTIES:
:CUSTOM_ID: Prose
:END:
Emacs can be setup with a spellchecker and other expected features of a word processing tool
---however these features apply Emacs-wide since nearly everything is
essentially text (•̀ᴗ•́)و
- Org-mode is a writer's best friend; it's large enough to deserve its own sections.
- See [[https://lucidmanager.org/tags/emacs/][Emacs Writing Studio]] for a series of articles on making/using Emacs for writing.
*** Bidirectional Text
#+begin_src emacs-lisp
;; Sometimes I have Arabic in my buffers, however I am an English speaker
;; and so Left-to-Right is most natural to me. As such, even when Arabic
;; is present, or any bidirectional text, just use Left-to-Right.
(setq-default bidi-paragraph-direction 'left-to-right)
#+end_src
*** Whitespace
:PROPERTIES:
:CUSTOM_ID: Whitespace
:END:
Let's start off by cleaning-up any accidental trailing whitespace and in other
places upon save.
#+begin_src emacs-lisp
(add-hook 'before-save-hook 'whitespace-cleanup)
#+end_src
See [[http://ergoemacs.org/emacs/whitespace-mode.html][here]] for making whitespace visible; including spaces, tabs, and newlines
*** Formatting Text
:PROPERTIES:
:CUSTOM_ID: Formatting-Text
:END:
The following incantation, doc:my/org-mode-format, makes it so that we can
select some text then press kbd:C-c_f (to get a list of possible character
completions) then press the symbol we want our text to be surrounded with.
#+begin_details
#+begin_src emacs-lisp
(local-set-key (kbd "C-c f") #'my/org-mode-format)
(defun my/org-mode-format (&optional text)
"Surround selected region with the given Org emphasises marker.
E.g., if this command is bound to “C-c f” then the sequence
“C-c f b” would make the currenly selected text be bold.
Likewise, “C-c f *” would achieve the same goal.
When you press “C-c f”, a message is shown with a list of
useful single-character completions.
Note: “C-c f 𝓍”, for an unrecognised marker 𝓍, just inserts
the character 𝓍 before and after the selected text."
(interactive "P") ;; Works on a region
; (message "b,* ⟨Bold⟩; i,/ ⟨Italics⟩; u,_ ⟨Underline⟩; c,~ ⟨Monotype⟩")
(message "⟨Bold b,*⟩ ⟨Italics i,/⟩ ⟨Underline u,_⟩ ⟨Monotype c,~⟩")
(let ((kind (read-char)))
;; Map letters to Org formatting symbols
(setq kind (or (plist-get '(b ?\* i ?\/ u ?\_ c ?\~)
(intern (string kind)))
kind))
(insert-pair text kind kind)))
#+end_src
#+end_details
*** Fill-mode ---Word Wrapping
:PROPERTIES:
:CUSTOM_ID: Fill-mode-Word-Wrapping
:END:
In fill mode, when you type past the end of a line, Emacs automatically starts a new line, cleverly formatting
paragraphs. This is a powerful form of “word wrap”.
#+BEGIN_SRC emacs-lisp
(setq-default fill-column 80 ;; Let's avoid going over 80 columns
truncate-lines nil ;; I never want to scroll horizontally
indent-tabs-mode nil) ;; Use spaces instead of tabs
#+END_SRC
Certain variables are sensibly local to a buffer, and so ~setq~ only alters their value for one buffer. Using ~setq-default~
we change a variable's default value, in every buffer.
#+BEGIN_SRC emacs-lisp
;; Wrap long lines when editing text
(add-hook 'text-mode-hook 'turn-on-auto-fill)
(add-hook 'org-mode-hook 'turn-on-auto-fill)
#+END_SRC
We may press ~M-q~ to cleverly redistribute the line breaks within any paragraph, thereby making it look better. With a
prefix argument, it justifies it as well ---i.e., pads extra white space to make the paragraph appear rectangular.
Note that ~M-o M-s~ centres a line of text ;-) Fun stuff!
Fill-mode is also known as “hard word wrapping”, which has the counterpart “soft word wrapping” …
Visual line mode is built-in and provides support for editing by visual lines: Lines off the screen are visually word
wrapped, but logically remain one line. Moreover =C-a,e,k= operate on visual lines rather than logical lines.
#+begin_src emacs-lisp
;; Bent arrows at the end and start of long lines.
(setq visual-line-fringe-indicators '(left-curly-arrow right-curly-arrow))
(global-visual-line-mode 1)
#+end_src
Visual line mode is useful when I have way too many windows open or when using smaller frames.
*** Fix spelling as you type ---thesaurus & dictionary too!
:PROPERTIES:
:CUSTOM_ID: Fix-spelling-as-you-type-thesaurus-dictionary-too
:END:
I would like to check spelling on the fly.
+ ~C-;~ :: Cycle through corrections for word at point.
+ ~M-$~ :: Check and correct spelling of the word at point
+ ~M-x ispell-change-dictionary RET TAB~ :: To see what dictionaries are available.
Install spell-checking application as well as a reliable English
dictionary, [[https://wordnet.princeton.edu/][WordNet]].
#+begin_src emacs-lisp
(unless noninteractive (system-packages-ensure "aspell"))
(unless noninteractive (system-packages-ensure "wordnet"))
#+end_src
~flyspell-prog-mode~ enables spell checking for programming by only considering
comments and strings.
#+BEGIN_SRC emacs-lisp
(use-package flyspell
:hook ((prog-mode . flyspell-prog-mode)
((org-mode text-mode) . flyspell-mode)))
#+END_SRC
Enabling fly-spell for text-mode enables it for org and latex modes since they
derive from text-mode.
Flyspell needs a spell checking tool, which is not included in Emacs. We
install ~aspell~ spell checker using, say, homebrew via ~brew install aspell~. Note
that Emacs' ~ispell~ is the interface to such a command line spelling utility.
# See available dictionary via ~aspell dicts~.
#+BEGIN_SRC emacs-lisp
(setq ispell-program-name (s-trim (shell-command-to-string "which aspell")))
(setq ispell-dictionary "en_GB") ;; set the default dictionary
#+END_SRC
[Disabled] Allow spelling support for CamlCase words like “EmacsIsCool”.
#+BEGIN_SRC emacs-lisp :tangle no
(setq ispell-extra-args '("--sug-mode=ultra"
"--run-together"
"--run-together-limit=5"
"--run-together-min=2"))
#+END_SRC
Let us select a correct spelling merely by clicking on a word
---for the rare days I have a mouse.
#+begin_src emacs-lisp
(eval-after-load "flyspell"
' (progn
(define-key flyspell-mouse-map [down-mouse-3] #'flyspell-correct-word)
(define-key flyspell-mouse-map [mouse-3] #'undefined)))
#+end_src
Colour incorrect works; default is an underline.
#+BEGIN_SRC emacs-lisp
(global-font-lock-mode t)
(custom-set-faces '(flyspell-incorrect ((t (:inverse-video t)))))
#+END_SRC
Finally, save to user dictionary without asking:
#+BEGIN_SRC emacs-lisp
(setq ispell-silently-savep t)
#+END_SRC
Let's keep track of my personal word set by having it be in my version controlled
.emacs directory. [[http://aspell.net/man-html/Format-of-the-Personal-and-Replacement-Dictionaries.html][Note]] that the default location is ~~/.[i|a]spell.DICT~ for
a specified dictionary ~DICT~.
#+BEGIN_SRC emacs-lisp
(setq ispell-personal-dictionary "~/.emacs.d/.aspell.en.pws")
#+END_SRC
Nowadays, I very rarely write non-literate programs, but if I do
I'd like to check spelling only in comments/strings. E.g.,
#+BEGIN_SRC emacs-lisp
(add-hook 'c-mode-hook 'flyspell-prog-mode)
(add-hook 'emacs-lisp-mode-hook 'flyspell-prog-mode)
#+END_SRC
Use the thesaurus Emacs frontend [[https://github.com/hpdeifel/synosaurus][Synosaurus]] to avoid unwarranted repetition.
#+begin_src emacs-lisp
(use-package synosaurus
:custom (synosaurus-choose-method 'popup)
:bind* ("M-#" . synosaurus-choose-and-replace))
#+end_src
The thesaurus is powered by the Wordnet ~wn~ tool, which can be invoked without an
internet connection!
#+begin_src emacs-lisp
;; (shell-command "brew cask install xquartz &") ;; Dependency
;; (shell-command "brew install wordnet &")
#+end_src
Let's use Wordnet as a dictionary via the [[https://github.com/gromnitsky/wordnut][wordnut]] package.
#+BEGIN_SRC emacs-lisp
(use-package wordnut
:defer 100
:bind ("M-!" . wordnut-lookup-current-word))
;; Use M-& for async shell commands.
#+END_SRC
Use ~M-↑,↓~ to navigate dictionary results, and ~wordnut-search~ for a new search.
An alternative to =wordnut= is to use the lightweight ~define-word~ package; which I
think is not ideal since it provides way less information.
:PowerthesaurusCurrentlyNotWorking:
#+BEGIN_SRC emacs-lisp :tangle no
(load "~/dotfiles/.emacs.d/powerthesaurus.el")
(global-set-key (kbd "M-#") 'powerthesaurus-lookup-word-at-point)
;; Website currently down ... https://github.com/SavchenkoValeriy/emacs-powerthesaurus/issues/6
#+END_SRC
:End:
*** Touch Typing :Disabled:
:PROPERTIES:
:CUSTOM_ID: Touch-Typing
:header-args: :tangle no
:END:
Use this game to help you learn to spell words that you're having trouble with;
e.g., I have a file ~~/Dropbox/spelling.txt~ with words I have trouble spelling,
which I open then run ~M-x typing-of-emacs~ in order to improve spelling said
words.
#+BEGIN_SRC emacs-lisp :tangle no
;; The Typing Of Emacs, a game.
(use-package typing-of-emacs
:quelpa (typing :fetcher wiki :url "https://www.emacswiki.org/emacs/typing.el"))
#+END_SRC
Practice touch typing using [[https://github.com/hagleitn/speed-type][speed-type]].
#+begin_src emacs-lisp
(use-package speed-type )
#+end_src
Running ~M-x speed-type-region~ on a region of text, or ~M-x speed-type-buffer~ on a
whole buffer, or just ~M-x speed-type-text~ will produce the selected region, buffer,
or random text for practice. The timer begins when the first key is pressed
and stats are shown when the last letter is entered.
Other typing resources include:
+ [[https://www.emacswiki.org/emacs/TypingOfEmacs][Typing of Emacs]] ---an Emacs alternative to speed type, possibly more engaging.
+ [[https://alternativeto.net/software/klavaro/][Klavaro]] ---a GUI based yet language-independent typing tutor.
- I'm enjoying this tool in getting started with Arabic typing.
+ [[https://typing.io/][Typing.io]] is a tutor for coders: Lessons are based on open source code, such
some XMonad written in Haskell or Linux written in C.
+ [[https://www.gnu.org/software/gtypist/index.html#downloading][GNU Typist]] ---which is interactive in the terminal, so not ideal in Emacs--,
To assist in language learning, it may be nice to have an Emacs
[[https://github.com/atykhonov/google-translate][interface]] to Google translate ---e.g., invoke ~google-translate-at-point~.
#+BEGIN_SRC emacs-lisp
(use-package google-translate
:config
(global-set-key "\C-ct" 'google-translate-at-point))
#+END_SRC
Select the following then ~C-c t~,
#+begin_quote
Hey buddy, what're you up to?
#+end_quote
Then /detect language/ then /Arabic/ to obtain:
#+begin_quote
مرحباً يا صديقي ، ماذا تفعل؟
#+end_quote
Neato 😲
*** Using a Grammar & Style Checker :Disabled:
:PROPERTIES:
:CUSTOM_ID: Using-a-Grammar-Style-Checker
:header-args: :tangle no
:END:
[ A possibly better alternative is [[https://emacstil.com/til/2022/03/05/setting-up-vale-prose-linter-on-emacs/][Vale]]. ]
Let's install [[https://github.com/mhayashi1120/Emacs-langtool][a grammar and style checker]].
We get the offline tool from the bottom of the [[https://languagetool.org/][LanguageTool]] website, then relocate it
as follows.
#+BEGIN_SRC emacs-lisp
(use-package langtool
:custom
(langtool-language-tool-jar
"~/Applications/LanguageTool-4.5/languagetool-commandline.jar"))
#+END_SRC
Now we can run ~langtool-check~ on the subsequent grammatically incorrect
text ---which is from the LanguageTool website--- which colours errors in red,
when we click on them we get the reason why; then we may invoke
~langtool-correct-buffer~ to quickly use the suggestions to fix each correction,
and finally invoke ~langtool-check-done~ to stop any remaining red colouring.
#+begin_example org
LanguageTool offers spell and grammar checking. Just paste your text here
and click the 'Check Text' button. Click the colored phrases for details
on potential errors. or use this text too see an few of of the problems
that LanguageTool can detecd. What do you thinks of grammar checkers?
Please not that they are not perfect. Style issues get a blue marker:
It's 5 P.M. in the afternoon. The weather was nice on Thursday, 27 June 2017
--uh oh, that's the wrong date ;-)
#+end_example
By looking around the source code, I can do all three stages smoothly (•̀ᴗ•́)و
#+BEGIN_SRC emacs-lisp
;; Quickly check, correct, then clean up /region/ with M-^
(eval-after-load 'langtool
(progn
(add-hook 'langtool-error-exists-hook
(lambda ()
(langtool-correct-buffer)
(langtool-check-done)))
(global-set-key "\M-^"
(lambda ()
(interactive)
(message "Grammar checking begun ...")
(langtool-check)))))
#+END_SRC
The checking command is silent, we added a bit of comforting acknowledgement to the user.
See also:
+ https://taonaw.com/2025/07/08/harper-quick-light-and-private.html
+ https://www.cyan.sh/blog/posts/goodbye-languagetool-hello-harper.html
+ https://writewithharper.com/docs/integrations/emacs
*** Lightweight Prose Proofchecking
:PROPERTIES:
:CUSTOM_ID: Lightweight-Prose-Proofchecking
:END:
Let's [[https://github.com/bnbeckwith/writegood-mode][write good]]!
#+BEGIN_SRC emacs-lisp
(use-package writegood-mode
:hook (text-mode org-mode) ;; Load this whenver I'm composing prose.
:config (cons writegood-weasel-words
'("it turns out that" ;; How does it turn out so? ;; ↯ What is the evidence of highighted phrase? ↯
"may have"
"experience shows"
"clearly"
"probably"
"easily"
"often"
"easy"
"simply"
"simple"
"some"
"many"
"various"
"very"
"fairly"
"several"
"extremely"
"exceedingly"
"quite"
"remarkably"
"few"
"surprisingly"
"mostly"
"largely"
"huge"
"tiny"
"are a number"
"is a number"
"excellent"
"interestingly"
"significantly"
"substantially"
"clearly"
"vast"
"relatively"
"completely"
"literally"
"not rocket science"
"outside the box"
"some"
"simple"
"simply"
"easy"
"often"
"easily"
"probably"
"clearly" ;; Is the premise undeniably true?
"experience shows" ;; Whose? What kind? How does it do so?
"may have"))) ;; It may also have not!
#+END_SRC
Inspired by Matt Might's [[http://matt.might.net/articles/shell-scripts-for-passive-voice-weasel-words-duplicates/][3 shell scripts to improve your writing, or
"My Ph.D. advisor rewrote himself in bash"]], this Emacs interface
emphasises, via underline, the following weaknesses in writing ---so
that I can fix them or decide that they are appropriate for the
scenario.
Sentences that cut out the following problems may become stronger
---by being more terse or precise.
+ Weasel Words ::
Phrases that sound good without conveying information;
such as vague precision or subjective phrases.
E.g., /a number of, surprisingly, very close/.
It's okay not to have exact details, but rather than “I don't know”
explain why not and what the next steps will be.
+ Passive Voice ::
Phrases wherein interest is in the object experiencing an action,
rather than the subject that performs the action.
- Bad: The house /was built by/ my father.
- Good: My father /built/ this house.
Likewise, including relevant or explanatory information as in “X
guarantees Y” is an improvement over “Y is guaranteed”.
Sometimes the subject really is irrelevant, such as
“We did X” whereas “X happened” suffices.
👍 If the relevant subject is unclear and, also, the text reads
better in the active, then change a phrase.
+ Duplicated Words :: Occurrences of, say, “the the”.
Harder to catch manually, but easier mechanically ;-)
*** Placeholder Text ---For Learning & Experimenting
:PROPERTIES:
:CUSTOM_ID: Placeholder-Text-For-Learning-Experimenting
:END:
When learning about Emacs formatting commands, such as zap-to-char ~M-z~
or transpose ~M-t~, it's best to have filler text ---even better when
it's automatically generated instead of typing it out ourselves. The
following will give us a series of commands ~lorem-ipsum-insert-⋯~ for
inserting lists, sentences, paragraphs and using a prefix argument,
with ~C-u~, we can request to generate any number of them.
#+BEGIN_SRC emacs-lisp
(use-package lorem-ipsum :defer t)
#+END_SRC
‘Lorem’ is not a word itself, but it comes from the Latin ‘Dolorem Ipsum’
which means “pain in and of itself”.
See this [[https://github.com/alhassy/emacs.d/blob/master/CheatSheet.pdf][Emacs Cheat Sheet]] to try out the textual navigation and formatting
bindings on lorem ipsum, gibberish text.
*** Some text to make us smile
:PROPERTIES:
:CUSTOM_ID: Some-text-to-make-us-smile
:END:
The [[https://github.com/davep/dad-joke.el][dad-joke]] queries [[https://icanhazdadjoke.com][https://icanhazdadjoke.com]] to bring us some funny.
#+begin_src emacs-lisp
(😴 use-package dad-joke
:config (defun dad-joke () (interactive) (insert (dad-joke-get))))
#+end_src
For example, ~M-x dad-joke~ now inserts:
#+begin_quote org
What are the strongest days of the week? Saturday and Sunday...the rest are
weekdays.
#+end_quote
*** Unicode Input via Agda Input
:PROPERTIES:
:CUSTOM_ID: Unicode-Input-via-Agda-Input
:END:
:agda2-include-dirs-Issue:
#+BEGIN_SRC emacs-lisp
;; (load (shell-command-to-string "agda-mode locate"))
;;
;; Seeing: One way to avoid seeing this warning is to make sure that agda2-include-dirs is not bound.
; (makunbound 'agda2-include-dirs)
#+END_SRC
:End:
[[https://mazzo.li/posts/AgdaSort.html][Agda]] is one of my favourite languages, it's like Haskell on steroids. Let's set
it up for the main sake of its Unicode input ---you may do likewise using TeX
input. ( [[https://www.joelonsoftware.com/2003/10/08/the-absolute-minimum-every-software-developer-absolutely-positively-must-know-about-unicode-and-character-sets-no-excuses/][The Absolute Minimum Every Software Developer Absolutely, Positively
Must Know About Unicode and Character Sets (No Excuses!)]] )
/Agda input mode makes it extremely easy to use unicode in documents, something I/
/strongly prefer to do. When I can use symbols directly, instead of (for/
/instance) LaTeX commands, it makes my plaintext far more readable./ --- [[https://github.com/armkeh/dotfiles/tree/master/emacs][Armkeh
.emacs config]]
#+begin_src emacs-lisp :tangle no
(system-packages-ensure "agda")
#+end_src
#+begin_details To use the Agda standard library by default
#+BEGIN_SRC shell :tangle no
mkdir -p ~/.agda
echo /usr/local/lib/agda/standard-library.agda-lib >>~/.agda/libraries
echo standard-library >>~/.agda/defaults
#+END_SRC
Invoke ~brew info agda~ to get these instructions and the version of Agda just
installed.
#+end_details
#+begin_details Get font support for subscripts, if need be
- Download and unzip the [[https://fontlibrary.org/en/font/symbola][symbola]] font
- kbd:CMD_+_SPC ⇒ =font book= ⇒ CMD+O ⇒ select the symbola directory you just
unzipped
(Note: In the before time, you could brew install this font.)
#+end_details
Executing ~agda-mode setup~ appends the following text to the ~.emacs~ file.
Let's put it here ourselves.
#+begin_src emacs-lisp :tangle no
(unless noninteractive
(load-file (let ((coding-system-for-read 'utf-8))
(shell-command-to-string "agda-mode locate"))))
#+end_src
I almost always want the ~agda-mode~ input method ---it's like the TeX method, but
better.
#+BEGIN_SRC emacs-lisp
;; TODO: Maybe don't bother installing Agda, and just get agda-input.el
;; from: https://github.com/agda/agda/blob/master/src/data/emacs-mode/agda-input.el
;; then loading that!
(-let [agda-input.el "~/.emacs.d/elpa/agda-input.el"]
(unless (f-exists? agda-input.el)
(url-copy-file "https://raw.githubusercontent.com/agda/agda/master/src/data/emacs-mode/agda-input.el" agda-input.el))
(load-file agda-input.el))
;; MA: This results in "Package cl is deprecated" !?
(unless noninteractive
(use-package agda-input
:ensure nil ;; I have it locally.
:demand t
:hook ((text-mode prog-mode) . (lambda () (set-input-method "Agda")))
:custom (default-input-method "Agda")))
;; Now C-\ or M-x toggle-input-method turn it on and offers
;; TODO add a hook that when the input method becomes Agda, just don't bother showing me in the modeline.
;; E.g., "Π" when using unicode input with Agda
;; Useful to have in the modeline, say when typing in Arabic.
;; (add-variable-watcher
;; 'current-input-method
;; (lambda (_ newvalue 'set _)
;; (setq current-input-method-title
;; (if (equal newvalue "Agda") nil newvalue))))
#+END_SRC
:agda_Command_line_arguments:
"+RTS -H4.5G -M4.5G -K256M -S/tmp/AgdaRTS.log -A1G -RTS -i ."
Wolfram Kahl has recommended the following settings.
#+begin_src emacs-lisp
;;(setq agda2-program-args (quote ("RTS" "-M4G" "-H4G" "-A128M" "-RTS")))
#+end_src
These arguments specify
| ~+RTS~, ~-RTS~ | Flags between these are arguments to the ~ghc~ runtime |
| ~-M[size]~ | Maximum heap size |
| ~-H[size]~ | Suggested heap size |
| ~-A[size]~ | Allocation area size used by the garbage collector |
Full documentation for the ~ghc~ runtime argumentscan be found [[https://downloads.haskell.org/~ghc/7.8.4/docs/html/users_guide/runtime-control.html][here]].
Additional arguments that may be useful include
| ~-S[file]~ | Produces information about “each and every garbage collection” |
| | - Outputs to ~stderr~ by default |
:end:
#+begin_quote
Unicode doesn't intend to cover things that are achievable with markup, so only
a limited subset of the alphabet is available as subscript; but all is available
as superscript, except ‘q’.
ₐₑₕᵢⱼₖₗₘₙₒₚᵣₛₜᵤᵥₓ
⁰ ¹ ² ³ ⁴ ⁵ ⁶ ⁷ ⁸ ⁹ ⁺ ⁻ ⁼ ⁽ ⁾ ₀ ₁ ₂ ₃ ₄ ₅ ₆ ₇ ₈ ₉ ₊ ₋ ₌ ₍ ₎
ᵃ ᵇ ᶜ ᵈ ᵉ ᶠ ᵍ ʰ ⁱ ʲ ᵏ ˡ ᵐ ⁿ ᵒ ᵖ ʳ ˢ ᵗ ᵘ ᵛ ʷ ˣ ʸ ᶻ
ᴬ ᴮ ᴰ ᴱ ᴳ ᴴ ᴵ ᴶ ᴷ ᴸ ᴹ ᴺ ᴼ ᴾ ᴿ ᵀ ᵁ ⱽ ᵂ
ᵅ ᵝ ᵞ ᵟ ᵋ ᶿ ᶥ ᶲ ᵠ ᵡ ᵦ ᵧ ᵨ ᵩ ᵪ
~brew cask install font-symbola~
⇒ Includes fonts for subscripts; e.g., ₐₙₑₕᵢⱼₖₗₘₙₒₚₜₛ
#+end_quote
Below are my personal Agda input symbol translations;
e.g., ~\set → 𝒮ℯ𝓉~. Note that we could give a symbol new Agda TeX binding
interactively: ~M-x customize-variable agda-input-user-translations~ then
~INS~ then for key sequence type ~set~ then ~INS~ and for string paste ~𝒮ℯ𝓉~.
#+BEGIN_SRC emacs-lisp
(unless noninteractive (add-to-list 'agda-input-user-translations '("set" "𝒮ℯ𝓉")))
#+END_SRC
Better yet, as a loop:
#+BEGIN_SRC emacs-lisp
(unless noninteractive
(cl-loop for item
in '(;; Arabic ornate parenthesis U+FD3E / U+FD3F
("(" "﴾")
(")" "﴿")
("cmd" "⌘")
;; categorial ;;
("alg" "𝒜𝓁ℊ")
("split" "▵")
("join" "▿")
("adj" "⊣")
(";;" "﹔")
(";;" "⨾")
(";;" "∘")
;; logic
("if" "⇐")
("onlyif" "⇒")
;; lattices ;;
("meet" "⊓")
("join" "⊔")
;; tortoise brackets, infix relations
("((" "〔")
("))" "〕")
;; residuals
("syq" "╳")
("over" "╱")
("under" "╲")
;; Z-quantification range notation ;;
;; e.g., “∀ x ❙ R • P” ;;
("|" "❙")
("with" "❙")
;; Z relational operators
("domainrestriction" "◁")
("domr" "◁")
("domainantirestriction" "⩤")
("doma" "⩤")
("rangerestriction" "▷")
("ranr" "▷")
("rangeantirestriction" "⩥")
("rana" "⩥")
;; adjunction isomorphism pair ;;
("floor" "⌊⌋")
("lower" "⌊⌋")
("lad" "⌊⌋")
("ceil" "⌈⌉")
("raise" "⌈⌉")
("rad" "⌈⌉")
;; Replies
("yes" "✔")
("no" "❌")
;; Arrows
("<=" "⇐")
;; more (key value) pairs here
)
do (add-to-list 'agda-input-user-translations item)))
#+END_SRC
Also some silly stuff:
#+begin_src emacs-lisp
(unless noninteractive
;; Add to the list of translations using “emot” and the given, more specfic, name.
;; Whence, \emot shows all possible emotions.
(cl-loop for emot
in `(;; angry, cry, why-you-no
("whyme" "ლ(ಠ益ಠ)ლ" "ヽ༼ಢ_ಢ༽ﾉ☂" "щ(゜ロ゜щ)" "‿︵(ಥ﹏ಥ)‿︵" "ಠ_ಠ" "(╬ ಠ益ಠ)" "･ﾟ(*❦ω❦)*･ﾟ" "(╯°□°）╯︵ ┻━┻") ;; flip the table
;; confused, disapprove, dead, shrug, awkward
("what" "「(°ヘ°)" "(ಠ_ಠ)" "(✖╭╮✖)" "¯\\_(ツ)_/¯" "(´°ω°`)" "･✧_✧･")
;; dance, csi
("cool" "┏(-_-)┓┏(-_-)┛┗(-_- )┓"
,(s-collapse-whitespace "•_•)
( •_•)>⌐■-■
(⌐■_■)"))
;; love, pleased, success, yesss, smile, excited, yay
("smile" "♥‿♥" "(─‿‿─)" "(•̀ᴗ•́)و" "ᕦ( ᴼ ڡ ᴼ )ᕤ" "(งಠ_ಠ)ง" "(｡◕‿◕｡)" "(◕‿◕)" "( ˃ ヮ˂)" "[ ⇀ ‿ ↼ ]" "٩(⁎❛ᴗ❛⁎)۶" "ᴵ’ᵐ ᵇᵉᵃᵘᵗⁱᶠᵘˡ" "(✿◠‿◠)")
;; flower high-5
("hug" "♡(✿ˇ◡ˇ)人(ˇ◡ˇ✿)♡" "(づ｡◕‿◕｡)づ" "(づ｡◕‿‿‿‿◕｡)づ"))
do
(add-to-list 'agda-input-user-translations emot)
(add-to-list 'agda-input-user-translations (cons "emot" (cdr emot)))))
#+end_src
# If you change this setting manually, without using the
# customization buffer, you need to call (agda-input-setup) in
# order for the change to take effect.
Finally let's effect such translations.
#+begin_src emacs-lisp
;; activate translations
(unless noninteractive (agda-input-setup))
#+end_src
Note that the effect of [[http://ergoemacs.org/emacs/emacs_n_unicode.html][Emacs unicode input]] could be approximated using
~abbrev-mode~.
:May_need_to_install_stix_font:
;; install STIX font from Ubuntu store!!
;; (set-fontset-font t 'unicode (font-spec :name "STIX") nil 'append)
:End:
*** Increase/decrease text size
:PROPERTIES:
:CUSTOM_ID: Increase-decrease-text-size
:END:
The ‘usual’ text zoom keys ~C-±~ …
#+BEGIN_SRC emacs-lisp
(global-set-key (kbd "C-+") 'text-scale-increase)
(global-set-key (kbd "C--") 'text-scale-decrease)
;; C-x C-0 restores the default font size
#+END_SRC
If thou knowst the ELisp, forgive this shadowing of the ~negative-argument~
… we've still got ~M--~ though.
Curious, this is one of the very first things I did when
began using Emacs; yet, perhaps I would not have done
it if I was simply told the defaults:
+ ~C-x C-=,+~ increases text size
+ ~C-x C--~ decreases test size
+ ~C-x C-0~ restores it to the default size
So, the above snippet seems to save us of the prefix
~C-x~ and we lose on using ‘=’ for text increase and worse we
need the shift-key to get access to the ‘+’.
I suppose this is just a habit inherited from using other tools. Fortunately, I
did not inherit the need for the /common user access/ bindings ~C-x~ kill, ~C-c~ copy,
~C-v~ paste, nor ~C-z~ undo of other applications. If you're interested, ~M-x
cua-mode~ to enable [[https://www.gnu.org/software/emacs/manual/html_node/emacs/CUA-Bindings.html][CUA Bindings]].
*** Moving Text Around
:PROPERTIES:
:CUSTOM_ID: Moving-Text-Around
:END:
This extends Org-mode's ~M-↑,↓~ to other modes, such as when coding.
#+BEGIN_SRC emacs-lisp
;; M-↑,↓ moves line, or marked region; prefix is how many lines.
(use-package move-text
:hook (after-init . move-text-default-bindings))
#+END_SRC
*** Enabling CamelCase Aware Editing Operations
:PROPERTIES:
:CUSTOM_ID: Enabling-CamelCase-Aware-Editing-Operations
:END:
[[https://www.gnu.org/software/emacs/manual/html_node/ccmode/Subword-Movement.html][Subword]] movement lets us treat “EmacsIsAwesome” as three words
─“Emacs”, “Is”, and “Awesome”─ which is desirable since such naming
is common among coders. Now, for example, ~M-f~ moves along each subword.
#+begin_src emacs-lisp
(global-subword-mode 1)
#+end_src
*** Mouse Editing Support :Disabled:
:PROPERTIES:
:CUSTOM_ID: Mouse-Editing-Support
:header-args: :tangle no
:END:
# :Strange:This_Seems_To_Require_Deprecated_CL:Message_show_at_startup:
Text selected with the mouse is automatically copied to clipboard.
#+begin_src emacs-lisp
(setq mouse-drag-copy-region t)
#+end_src
*** Delete Selection Mode
:PROPERTIES:
:CUSTOM_ID: Delete-Selection-Mode
:END:
Delete Selection mode lets you treat an Emacs region much like a typical text
selection outside of Emacs: You can replace the active region. We can delete
selected text just by hitting the backspace key.
#+BEGIN_SRC emacs-lisp
(delete-selection-mode 1)
#+END_SRC
*** ~M-n,p~: Word-at-Point Navigation ╱╲ Automatic highlighting current symbol/word :Disabled:
:PROPERTIES:
:CUSTOM_ID: M-n-p-Word-at-Point-Navigation
:header-args: :tangle no
:END:
Let's mimic the ~C-n,p~ constructs from line to word, so that unoccupied ~M-n,p~ now
serve to take us to the next or previous instance of the word under the
cursor. This is less intrusive than searching ~C-s~ or listing all occurrences ~M-s
o~. Moreover, let's automaticly highlight current symbols, words under the cursour, and cycle
quickly between highlkighted locations with
~ahs-forward~ / [[kbd:M-→]] and
~ahs-backward~ / [[kbd:M-←]].
#+BEGIN_SRC emacs-lisp
;; Default: M-→/← moves to the next/previous instance of the currently highlighted word
;; These are already meaningful commands in Org-mode, so we avoid these key re-bindings in Org-mode; TODO.
(use-package auto-highlight-symbol)
;; :hook ((text-mode . auto-highlight-symbol-mode)
;; (prog-mode . auto-highlight-symbol-mode)))
;;
;; This breaks Org Exports; e.g.,
;; C-c C-e h o ⇒ Match data clobbered by buffer modification hooks
#+END_SRC
Let's also quickly replace the word at point:
#+BEGIN_SRC emacs-lisp
(defun my/symbol-replace (replacement)
"Replace all standalone symbols in the buffer matching the one at point."
(interactive (list (read-from-minibuffer "Replacement for thing at point: " nil)))
(save-excursion
(let ((symbol (or (thing-at-point 'symbol) (error "No symbol at point!"))))
(beginning-of-buffer)
;; (query-replace-regexp symbol replacement)
(replace-regexp (format "\\b%s\\b" (regexp-quote symbol)) replacement))))
#+END_SRC
(Unfortunately, as it currently is, there is no universal argument support: ~C-u
2 M-p~ does /not/ take you to the second previous instance of a word ---the prefix
is instead ignored. We can quickly form a work-around with doc:defhydra ---which
gives us temoporary modal modes.)
Finally, let's use [[kbd:M-n ╱ M-p ╱ M-']] to move to the next, previous, and
replace the word at point /but also/ to give us a meanu to repeat any of these
actions.
#+BEGIN_SRC emacs-lisp
(defmacro my/make-navigation-hydra (initial-action)
`(defhydra word-navigation
(:body-pre (,initial-action)) "Word-at-point Navigation"
("n" ahs-forward "Next instance")
("p" smartscan-symbol-go-backward "Previous instance")
("r" my/symbol-replace "Replace all occurances")
("s" ahs-display-stat "Stats")))
;; (bind-key* str func) ≈ (global-set-key (kbd str) func)
(bind-key* "M-n" (my/make-navigation-hydra ahs-forward))
(bind-key* "M-p" (my/make-navigation-hydra ahs-backward))
(bind-key* "M-'" (my/make-navigation-hydra my/symbol-replace))
#+END_SRC
An alternative is the [[https://github.com/mickeynp/smart-scan][smart-scan]] library ---which does the same thing, but does
not provide the highlighting occurances at point.
# The default symbol replacement is [[https://github.com/mickeynp/smart-scan/issues/23][over-zealous]] in that it replaces sub-terms
# occurring as parts of larger words. Let's do something about that.
*** Letter-based Navigation :Disabled:
:PROPERTIES:
:CUSTOM_ID: Letter-based-Navigation
:header-args: :tangle no
:END:
At a glance of possible positions, across windows,
and a key to jump there is a feature provided to us by [[https://github.com/winterTTr/ace-jump-mode/wiki/AceJump-FAQ][ace-jump]]
---here is an [[https://www.youtube.com/watch?feature=player_embedded&v=UZkpmegySnc#!][emacs-rocks 2-minute video]].
For example, =C-c SPC m= greys our all windows and places a red
letter at the start of any word that begins with /m/, then I may
press a letter to jump to the associated position in the
associated window. Using ~C-u C-c SPC~ and ~C-u C-u C-c SPC~ let
me jump to any character or to any visible line.
➩ Super simple use case: Fix your eyes on an occurence of a word, then ~C-c SPC~
to quickly jump to it so as to edit the sentence in which it occurs.
- It's like ~C-s~ but more lightweight.
#+begin_src emacs-lisp
(use-package ace-jump-mode
:config (bind-key* "C-c SPC" 'ace-jump-mode))
;; See ace-jump issues to configure for use of home row keys.
#+end_src
There is a newer and somewhat more powerful package, [[https://github.com/abo-abo/avy][avy]], which accompishes the
same goal. It uses a tree style to jumipng: Locations are given two letter
combinations, one presses one letter to jump to a group of text, then another
letter to jump somewhere in that grouping. I prefer ace-jump since it greys
everthing out, whereas avy surrounds jump locations with a box.
Here is an [[https://www.youtube.com/watch?v=zar4GsOBU0g][emacs-doom 6-minute video]] for avy.
There is also [[https://github.com/tam17aki/ace-isearch][ace-isearch]] for bridinging different navgiational methods ---one
begins incremental search, ~s-f~, then according to a pause and length of input,
one of the navgiational methods, such as isearch or avy or helm-occur, will be
begun. I'm okay with using ~C-s~ for helm-occur and ~C-c SPC~ for ace-jump, and
still have ~s-f~ for incremental search, which I hardly use.
*What is bind-keys**?
Major modes provide specfic use and so their bindings always take precedence
over global bindings ---e.g., the major mode binding may do what the global does
but with extra mode-specfic behaviour, such as indentation. Other times, a major
mode's binding simply uses the same key presses with completely unrelated
behaviour. If we want to avoid having our global keybindings shadowed by a
major mode, we may use the ~bind-key*~ /macro/ of ~use-package~, or the ~bind-keys*~
/macro/ when there are multiple keys; these are macros, not clauses. ---These
essentially creates a dedicated minor mode behind the scenes, which saves us the
work of [[https://emacs.stackexchange.com/a/358/10352][doing it ourselves]].
| | ~(bind-keys* (k₁ . f₁) … (kₙ . fₙ))~ |
| ≈ | These keybindings override all minor modes that use keys =kᵢ=. |
Of course we can also use it without the asterisk; e.g.:
#+begin_src emacs-lisp
;; C-x o ⇒ Switch to the other window
;; C-x O ⇒ Switch back to the previous window
(bind-key "C-x O" (lambda () (interactive) (other-window -1)))
#+end_src
Finally, we can use ~M-x describe-personal-keybindings~ to see the keybindings
we've personally defined in ~init.el~.
*** =C-c e n,p=: Taking a tour of one's edits :Disabled:
:PROPERTIES:
:CUSTOM_ID: C-c-e-n-p-Taking-a-tour-of-one's-edits
:header-args: :tangle no
:END:
This package allows us to move around the edit points of a buffer /without/
actually undoing anything. We even obtain a brief description of what happend at
each edit point. This seems useful for when I get interrupted or lose my train
of thought: Just press [[kbd:C-c e p]] to see what I did recently and where ---the
“e” is for “e”dit.
#+BEGIN_SRC emacs-lisp
;; Give me a description of the change made at a particular stop.
(use-package goto-chg
:custom (glc-default-span 0))
(my/defhydra "C-c e" "Look at them edits!" bus
:\ ("p" goto-last-change "Goto nᵗʰ last change")
("n" goto-last-change-reverse "Goto more recent change"))
#+END_SRC
Compare this with ~C-x u~, or ~undo-tree-visualise~, wherein undos are actually performed.
Notice, as a hydra, I can use ~C-c e~ followed by any combination of ~p~ and ~n~ to
navigate my recent edits /without/ having to supply the prefix each time.
*** visual-regexp
:PROPERTIES:
:CUSTOM_ID: visual-regexp
:END:
#+begin_src emacs-lisp
;; While constructing the regexp in the minibuffer, get live visual feedback for the (group) matches.
;; E.g., try: M-% use-\(.+?\) \(.+\)\b ENTER woah \1 and \2
;;
(use-package visual-regexp
:bind* ("M-%" . (lambda (&optional prefix)
"C-u M-% to do regexp replace, without querying."
(interactive "P")
(call-interactively (if prefix #'vr/replace #'vr/query-replace)))))
#+end_src
*** LaTeX ⇐ Org-Mode :Disabled:
:PROPERTIES:
:CUSTOM_ID: Org-Mode-PDF-HTML
:header-args: :tangle no
:END:
In this section we consider the Org-mode export for PDFs (LaTeX).
For example, we account for LaTeX citations.
# Installing LaTex
# $ brew install --cask mactex
# $ eval "$(/usr/libexec/path_helper)"
# $ type pdflatex # => pdflatex is /Library/TeX/texbin/pdflatex
#
# The ~minted~ environment can't appear as an argument to another command; a
# [[https://tex.stackexchange.com/questions/102416/error-when-compiling-a-minted-listings-inside-a-memoir-subfloat][work-around]] is to use a ‘box’. Learn more about LaTeX boxes [[https://latexref.xyz/Boxes.html][here]].
**** Get LaTeX:
:PROPERTIES:
:CUSTOM_ID: Get-LaTeX
:END:
# +begin_src shell
# time brew cask install mactex-no-gui
# +end_src
#+begin_src emacs-lisp
(system-packages-ensure "mactex")
#+end_src
- This is a redistribution of TeX Live specifically for macOS.
- We get the 4GB version since it has [[https://tex.stackexchange.com/a/1041/69371][everything]] and so
do not need to worry about missing style files.
- This took about 12 minutes on my machine.
Restart Emacs, enter =$e^{i \cdot \pi} + 1 = 0$= then press kbd:C-c_C-x_C-l to
have it rendered inline.
+ *Minted:* Get tool for colourful code snippets for LaTeX ---see “minted” in
the main article.
#+begin_src emacs-lisp
(system-packages-ensure "pygments")
#+end_src
+ *Not anymore:* Get a neato PDF presentation console: =brew install pdfpc=
- With =pdfpc myfile.pdf= you get a nice timer and multiple views
of the current slide and upcoming slides ---with support for multiple monitors.
- Install ScreenBrush, from the Apple Store, for easily drawing/annotating my
screen ---e.g., when I'm giving a virtual lecture to my students.
- An alternative is =brew install mupdf= then =mupdf-gl myfile.pdf= and press
=f= for fullscreen then =a= for adding/adorning drawings ---it was too
rough to use live.
Finally, within Emacs: =M-x pdf-tools-install=
:Possibly_breaking_toc-org:
#+BEGIN_SRC emacs-lisp :tangle no
;; Use 3 headlines of export, which is the default
;; (setq org-export-headline-levels 4)
;; no numbers by default at export
;; (setq org-export-with-section-numbers nil)
#+END_SRC
:End:
**** Working with Citations :Disabled:Not_Used:
:PROPERTIES:
:CUSTOM_ID: Working-with-Citations
:END:
# TODO Fix me, breaking Github Actions test setup
[[https://github.com/jkitchin/org-ref][An exquisite system]] for handling references.
The following entity will display useful data
when the mouse hovers over it (•̀ᴗ•́)و If you click on it, then you're
in for a lot of super neat stuff, such as searching for the pdf online!
cite:agda_overview ( In HTML export, the citation doesn't link anywhere. )
#+BEGIN_SRC emacs-lisp :tangle no
(unless noninteractive
(use-package org-ref
:custom ;; Files to look at when no “╲bibliography{⋯}” is not present in a file.
;; Most useful for non-LaTeX files.
(reftex-default-bibliography '("~/thesis-proposal/papers/References.bib"))
(bibtex-completion-bibliography (car reftex-default-bibliography))
(org-ref-default-bibliography reftex-default-bibliography))
;; Quick BibTeX references, sometimes.
(use-package helm-bibtex)
(use-package biblio) )
#+END_SRC
Execute ~M-x helm-bibtex~ or =C-c ]= and, say, enter =emacs= and you will be
presented with all the entries in the bib database that mention ‘emacs’. Super
cool stuff. Moreover, if no such entries exist, then we can look some up
using the interface!
Read the manual [[https://github.com/jkitchin/org-ref/blob/master/org-ref.org][online]] or better yet as an org-file with ~M-x org-ref-help~.
This is an Org-mode application since the citations have tooltips and export
nicely to LaTeX & HTML via the Org-mode exporter.
**** Bibliography & Coloured LaTeX using Minted
:PROPERTIES:
:CUSTOM_ID: Bibliography-Coloured-LaTeX-using-Minted
:END:
Execute the following for bibliography references as well as minted Org-mode
uses the Minted package for source code highlighting in PDF/LaTeX ---which in
turn requires the pygmentize system tool.
#+BEGIN_SRC emacs-lisp
(setq org-latex-listings 'minted
org-latex-packages-alist '(("" "minted"))
org-latex-pdf-process
'("pdflatex -shell-escape -output-directory %o %f"
"biber %b"
"pdflatex -shell-escape -output-directory %o %f"
"pdflatex -shell-escape -output-directory %o %f"))
#+END_SRC
For faster pdf generation, possibly with errors, consider invoking:
#+begin_example emacs-lisp
(setq org-latex-pdf-process
'("pdflatex -interaction nonstopmode -output-directory %o %f"))
#+end_example
By default, Org exports LaTeX using the ~nonstopmode~ option, which tries
its best to produce a PDF ---which ignores typesetting errors altogether,
which is not necessary ideal when using LaTeX.
**** COMMENT Excellent PDF Viewer
:PROPERTIES:
:CUSTOM_ID: Excellent-PDF-Viewer
:END:
Need to (re)build the epdfinfo program, do it now ? (y or n) n
--------------------------------------------------------------------------------
Let's install the [[https://github.com/politza/pdf-tools][pdf-tools]] library for viewing PDFs in Emacs.
#+BEGIN_SRC emacs-lisp
(use-package pdf-tools
; :init (system-packages-ensure "pdf-tools")
:custom (pdf-tools-handle-upgrades nil)
(pdf-info-epdfinfo-program "/usr/local/bin/epdfinfo")
:config (pdf-tools-install))
;; Now PDFs opened in Emacs are in pdfview-mode.
#+END_SRC
Besides the expected PDF viewing utilities, such as search, annotation, and continuous scrolling;
with a simple mouse right-click, we can even select a ‘midnight’ rendering mode which may be
easier on the eyes. For more, see the brief [[https://www.dailymotion.com/video/x2bc1is][pdf-tools-tourdeforce]] demo.
*** HTML ⇐ Org-mode
:PROPERTIES:
:CUSTOM_ID: HTML-Org-mode
:END:
In this section we consider the Org-mode exporters for PDFs and
HTMLs. For example, we account for LaTeX citations and reliable HTML
anchors.
#+BEGIN_SRC emacs-lisp
(use-package htmlize :defer t)
;; Main use: Org produced htmls are coloured.
;; Can be used to export a file into a coloured html.
#+END_SRC
**** HTML “Folded Drawers” :Move_to_org_special_block_extras:
:PROPERTIES:
:CUSTOM_ID: HTML-Folded-Drawers
:END:
#+BEGIN_SRC emacs-lisp :tangle no
(defun my/org-drawer-format (name contents)
"Export to HTML the drawers named with prefix ‘fold_’, ignoring case.
The resulting drawer is a ‘code-details’ and so appears folded;
the user clicks it to see the information therein.
Henceforth, these are called ‘fold drawers’.
Drawers without such a prefix may be nonetheless exported if their
body contains ‘:export: t’ ---this switch does not appear in the output.
Thus, we are biased to generally not exporting non-fold drawers.
One may suspend export of fold drawers by having ‘:export: nil’
in their body definition.
Fold drawers naturally come with a title.
Either it is specfied in the drawer body by ‘:title: ⋯’,
or otherwise the drawer's name is used with all underscores replaced
by spaces.
"
(let* ((contents′ (replace-regexp-in-string ":export:.*\n?" "" contents))
(fold? (s-prefix? "fold_" name 'ignore-case))
(export? (string-match ":export:\s+t" contents))
(not-export? (string-match ":export:\s+nil" contents))
(title′ (and (string-match ":title:\\(.*\\)\n" contents)
(match-string 1 contents))))
;; Ensure we have a title.
(unless title′ (setq title′ (s-join " " (cdr (s-split "_" name)))))
;; Output
(cond
((and export? (not fold?)) contents′)
(not-export? nil)
(fold?
(thread-last contents′
(replace-regexp-in-string ":title:.*\n" "")
(format " " title′))))))
(setq org-html-format-drawer-function 'my/org-drawer-format)
#+END_SRC
With the following invocations we only see the odd indexed ‘hello’s, where the
latter two are folded up.
#+BEGIN_SRC org :tangle no
:this-drawer-is-exported:
:export: t
hello 1
:End:
:this-drawer-is-NOT-exported:
hello 2
:End:
:fold_This_drawer_has_a_title_in_the_body:
:title: I am the drawer title 0
hello 3
:End:
:fold_This_drawer_is_NOT_exported:
:title: Why are we here?
:export: nil
hello 4
:End:
:fold_I_am_the_drawer_title_1:
hello 5
:End:
#+END_SRC
I doubt I could show an example in the Github README, since no HTML export is
happening using my setup. In case you're reading this on my blog, which has
exported HTML. Here's the example:
:fold_hello_world:
:title: ¡Hola! Buenas tardes, Amigo
Hey bud, hope you're enjoying this read ^_^
:End:
Now that I've written this, I'm thinking it may have been preferably to use an org-block…?
**** Diagrams with Mermaid ---Not Recommended :Disabled:
:PROPERTIES:
:CUSTOM_ID: Diagrams-with-Mermaid-Not-Recommended
:header-args: :tangle no :eval no-export
:END:
Let's try out an alternative to PlantUML ---covered below in §[[Workflow States]].
First, let's get the tool.
#+BEGIN_SRC shell :tangle no
npm install mermaid.cli
sudo git clone git@github.com:arnm/mermaid-layer.git ~/.emacs.d/private/mermaid
#+END_SRC
Then, let's get the associated ~mermaid~ package.
#+BEGIN_SRC emacs-lisp
(use-package ob-mermaid
:custom ob-mermaid-cli-path "~/node_modules/.bin/mmdc")
#+END_SRC
Then, =C-c C-c= on the following:
#+BEGIN_SRC mermaid :file test.png :theme neutral :background-color green :tangle no :results replace :eval never-export
sequenceDiagram
A-->B: Works!
#+END_SRC
#+RESULTS:
[[file:test.png]]
+ =C-c C-x C-v= ⇒ Show images inline
+ Mermaid supported headers:
- ~file~ to name the svg/png/pdf output
- ~width~ or ~height~ or the resulting image
- ~theme~ used, such as ~default, forest, dark, neutral~, for foreground entities
- ~background-color~ such as ~transparent, red, #F0F0F0~
* The transparent option is nice ^_^
+ You can insert new lines using ~
~ and horizontal rules via ~
~. Similarly you can use other HTML tags such as ~~; if you have too many
you can make CSS file then use the header argument ~:css-file~.
+ Add “non-breaking space” with ~ ~. This is a forced extra space and it prevents
a line break at its location. You can insert it repeatedly, but for two spaces
use ~ ~ and for four spaces use ~ ~.
If link text cuts off prematurely, use extra space /with/ a newline: ~A-- text
-->B~. *Warning*: JavaScript has some issues when working with Unicode and so, being a JavaScript utility, ~mermaid~ hangs when Unicode is used. On the upside, being a JavaScript utility, ~mermaid~ entities can have [[https://mermaid-js.github.io/mermaid/#/flowchart?id=interaction][arbitrary code attached]] to them to be executed upon clicks ---for use in browsers. - However, the Greek letters are supported; e.g., γ and Σ. See [[https://mermaid-js.github.io/mermaid/#/flowchart?id=nodes-amp-shapes][here]] for possible node shapes. #+begin_quote After forming an intricate diagram of related design patterns, I had to use a number of HTML notions, such as =, , ,, ,
,#+MACRO: fold #+HTML: \" color)
\"
\"))
"
(let ((func-name (intern (format "org-deftag/%s" name))))
`(progn
(cl-defun ,func-name (o-backend)
,docstring
(outline-show-all)
(org-map-entries
(lambda ()
(-let [(&alist ,@ (mapcar #'symbol-name args)) (map-apply (lambda (k v) (cons (downcase k) v)) (org-entry-properties (point)))]
;; MA: Maybe get rid of o-heading and o-properties and let people operate on raw Org secitons
;; as they do with org-agenda. That might provide a more unified approach.
(let ((o-properties (map-into (map-apply (lambda (k v) (cons (intern (concat ":" (downcase k))) v)) (org-entry-properties (point))) 'plist))
(o-heading (progn (kill-line) (car kill-ring))))
(if (not (s-contains? (format ":%s" (quote ,name)) o-heading 'ignoring-case))
(insert o-heading)
(setq o-heading (s-replace-regexp (format ":%s[^:]*:" (quote ,name)) "" o-heading))
,@body)
;; Otherwise we impede on the auto-inserted “* footer :ignore:”
(insert "\n"))))))
(add-hook 'org-export-before-parsing-hook (quote ,func-name))
)))
;; MA: This is new stuff.
(put 'org-deflink 'lisp-indent-function 'defun)
(put 'org-deftag 'lisp-indent-function 'defun)
;; Example use
(org-deftag identity ()
"Do nothing to Org headings"
(insert o-heading)) ;; Wait, I think this strips tags?
(org-deftag disabled (color)
"Render the body of a heading in a \" (s-replace-regexp \"^\** \" \"\" o-heading) \"
\") (org-next-visible-heading 1) (insert \"#+html: element, titled “Disabled”.
The heading remains in view, and so appears in the TOC."
(insert "\n") (insert o-heading) (insert "\n")
(insert "\n#+html:"
(format " "))
#+end_src
** Jumping to extreme semantic units
:PROPERTIES:
:CUSTOM_ID: Jumping-to-extreme-semantic-units
:END:
[[https://github.com/DamienCassou/beginend][Sometimes it's unreasonable]] for ~M-<~ to take us to the actual start of a buffer;
instead it'd be preferable to go to the first “semantic unit” in the buffer. For
example, when directory editing with ~dired~ we should jump to the first file,
with version control with ~magit~ we should jump to the first section, when
composing mail we should jump to the first body line, and in the agenda we
should jump to the first entry.
#+BEGIN_SRC emacs-lisp
;; M-< and M-> jump to first and final semantic units.
;; If pressed twice, they go to physical first and last positions.
(use-package beginend
:config (beginend-global-mode))
#+END_SRC
** Folding within a subtree
:PROPERTIES:
:CUSTOM_ID: Folding-within-a-subtree
:END:
#+begin_src emacs-lisp
(bind-key "C-c C-h"
(defun my/org-fold-current-subtree-anywhere-in-it ()
(interactive)
(save-excursion (save-restriction
(org-narrow-to-subtree)
(org-shifttab)
(widen))))
org-mode-map)
#+END_SRC
** Buffer default mode is org-mode
:PROPERTIES:
:CUSTOM_ID: Buffer-defaults
:END:
- I’d much rather have my new buffers in org-mode than fundamental-mode:
#+begin_src emacs-lisp
(setq-default major-mode 'org-mode)
#+end_src
** ox-pandoc
:PROPERTIES:
:CUSTOM_ID: Easy-tasks
:END:
# ox-pandoc is "another exporter that translates Org-mode file to various other formats via Pandoc".
# (shell-command "brew install pandoc")
# (use-package ox-pandoc)
** Org-mode's ~<𝒳~ Block Expansions
:PROPERTIES:
:CUSTOM_ID: Org-mode's-𝒳-Block-Expansions
:END:
In org-mode we type ~ D;
A -> B;
D -> C;
B -> C;
C -> C;
}
#+END_SRC
** No code evaluation upon export
#+begin_src emacs-lisp
;; Ignore all header arguments relating to “:eval”. Do not evaluate code when I export to HTML or LaTeX or anything else.
(setq org-export-use-babel nil)
#+end_src
** COMMENT Snippets ---Template Expansion & Completion :Disabled:I_have_not_used_this_in_some_time:
:PROPERTIES:
:CUSTOM_ID: Snippets-Template-Expansion
:header-args: :tangle no
:END:
It is common that there is a sequence of text that we tend to repeat
often, possibly with a name or some other parameter altered.
Such a ‘snippet’ could be written once then provided by a simple
Lisp insert command with the parameters being queried. Luckily, others
have written such pleasant utilities.
Besides snippets, there are words that we may want to repeat often but it can be
tedious to write them out in full. As such, we employ *[[green: word completion]]*;
which we also use to expand our snippets.
# For instance, I knew someone who writes ‘U’ all over the place
# since the word “universe” is too long to write
# and Emacs doesn't come with word completion.
*** Intro to Snippets
:PROPERTIES:
:CUSTOM_ID: Intro-to-Snippets
:END:
A *snippet, template, mechanism* is a tool that when you press some keystrokes
inserts some text, possibly with some fields (‘blanks’) to fill in. Possibly
interesting read:
+ [[https://cupfullofcode.com/blog/2013/02/26/snippet-expansion-with-yasnippet/index.html][Snippet Expansion With Yasnippet: Save Yourself Keystrokes and Headaches]]
---a nice before introduction to Yasnippet (“Yet another snippet”)
+ [[https://jpace.wordpress.com/2012/10/20/tweaking-emacs-snippets/][Tweaking Emacs: Snippets]] ---a brief article on using snippets for uniformity
across languages and to mitigate verbosity of weak languages (i.e., those
without macros).
--------------------------------------------------------------------------------
[[http://joaotavora.github.io/yasnippet/snippet-development.html][Yasnippet]] is a pleasant utility for template expansion with the alluring
feature to allow arbitrary Lisp code to be executed during expansion.
The declaration of templates is verbose, requiring a particular file
hierarchy, as such I utilise [[https://github.com/Kungsgeten/yankpad][Yankpad]] which allows me to employ
an Org-mode approach: Each template corresponds to an org heading of
the form ~Key:Words:For:Expansion:Here: name of snippet here~ and the
template body is then the body of the org heading.
Any of ~Key, Words, For, Expansion, Here~ will rewrite into the body
of the org tree. This is much more terse, and I even don't bother
with that; instead preferring to tangle my templates using yankpad
as a mere interface. It is important to note that Yankpad also provides
features that are not in Yassnippet, such as allowing arbitrary language
code to be executed ---one simply uses an org-src block!
| [[https://www.philnewton.net/blog/exploring-emacs-yasnippet/][Here]] is a nice self-contained tutorial. |
| Also, [[https://www.reddit.com/r/emacs/comments/o282fq/yasnippet_snippetstemplating_introductiontutorial/][YASnippet snippets/templating Introduction/Tutorial — Straightforward Emacs: emacs]] |
There can only be one major completion backend for any mode, but
other backends can serve as secondary ones. Here's a function to
make ~company-yankpad~ a secondary of all existing backends.
#+begin_src emacs-lisp
;; Add yasnippet support for all company backends
;;
(cl-defun my/company-backend-with-yankpad (backend)
"There can only be one main completition backend, so let's
enable yasnippet/yankpad as a secondary for all completion
backends.
Src: https://emacs.stackexchange.com/a/10520/10352"
(if (and (listp backend) (member 'company-yankpad backend))
backend
(append (if (consp backend) backend (list backend))
'(:with company-yankpad))))
#+end_src
#+begin_src emacs-lisp
;; Yet another snippet extension program
(use-package yasnippet
:config
(yas-global-mode 1) ;; Always have this on for when using yasnippet syntax within yankpad
;; respect the spacing in my snippet declarations
(setq yas-indent-line 'fixed))
;; Alternative, Org-based extension program
(use-package yankpad
:config
;; Location of templates
(setq yankpad-file "~/.emacs.d/yankpad.org")
;; Ignore major mode, always use defaults.
;; Yankpad will freeze if no org heading has the name of the given category.
(setq yankpad-category "Default")
;; Load the snippet templates ---useful after yankpad is altered
(yankpad-reload)
;; Set company-backend as a secondary completion backend to all existing backends.
(setq company-backends (mapcar #'my/company-backend-with-yankpad company-backends)))
#+end_src
With these settings, along with the ~company~ backend, I may type a keyword then
kbd:TAB it into expansion.
Yankpad requires we have an org file that contains our templates, so we /tangle/
such a file ~~/.emacs.d/yankpad.org~, and have all of our templates be globally
accessible. Here is the start of my file:
#+BEGIN_SRC org :tangle "~/.emacs.d/yankpad.org" :comments none
,#+Description: This is file is generated from my init.org; do not edit.
,* Default :global:
#+end_src
#+begin_details Fully discussed example: Using the clipboard for Org-links
Here's an example of a common template I perform by hand ---no more! I have the
expected habit of /copying (to clipboard)/ a URL from someplace then forming a
link to it by writing ~[[URL] [description]]~, since the URL & syntax are already
known, let's expand those and place the cursour at the only unknown ---the
description.
#+begin_src org :tangle "~/.emacs.d/yankpad.org" :comments none
,** my_org_insert_link: cleverly insert a link copied to clipboard
[[${1:`(clipboard-yank)`}][$2]] $0
#+end_src
What's going on here? ( The above, verbatim: ~[[${1:`(clipboard-yank)`}][$2]] $0~. )
0. This template is expanded with the keyword ~my-org-insert-link~, then kbd:TAB.
1. The cursour lands at position ~$1~, which has default text being the result
of evaluating ~(clipboard-yank)~.
# I've ‘documented’ this default as being the url.
# If I leave out the ~$(clipboard-yank)~ part, the default would simply be ~url~ pasted in.
We may evaluate Lisp code anywhere by enclosing it in backticks.
# `(file-name-nondirectory (file-name-sans-extension (buffer-file-name)))`
2. If we're satisfied with the current field, we simply tab to the next field.
Otherwise, we simply write text ---which overwrites the default text.
3. After enough tabbing we complete the template and the cursour lands
at position ~$0~.
⟪ Having default or mirrored text for ~$2~ would not allow me to see the URL
field, lest I wish to change it or at least confirm it's what I want.
Hence, the ~$2~ field has no default. ⟫
Let's overwrite the usual way to insert such links, via ~C-c C-l~.
#+BEGIN_SRC emacs-lisp
(cl-defun org-insert-link ()
"Makes an org link by inserting the URL copied to clipboard and
prompting for the link description only.
Type over the shown link to change it, or tab to move to the
description field.
This overrides Org-mode's built-in ‘org-insert-link’ utility;
whence C-c C-l uses the snippet."
(interactive)
(insert "my_org_insert_link")
(yankpad-expand))
#+END_SRC
#+end_details
/Warning!/ Snippet names cannot have hypens in them ---in this setup at least.
The [[http://joaotavora.github.io/yasnippet/snippet-development.html][Yasnippet manual]] is an accessible read, as is the [[https://github.com/Kungsgeten/yankpad][Yankpad manual]], and
showcases many other utilities; such as having certain snippets being
enabled only in particular modes or on demand. Of note is that field ~$n~ can be
accessed in code with the invocation ~(yas-field-value n)~.
Incidentally, I used this snippet setup to [[https://www.youtube.com/watch?v=NYOOF9xKBz8&feature=youtu.be][demo]] the idea of repetitious code in
grouping constructs within dependently-typed languages, which was accepted and
led to my doctoral research on a [[https://alhassy.github.io/next-700-module-systems/][‘do it yourself module system’]].
The rest of this section is other templates, not much for now,
concluding with actually loading this snippet mechanism globally.
The remaining subsections discuss contents of my yankpad file.
*** Org-mode Templates ---A reason I “generate” templates ;)
:PROPERTIES:
:CUSTOM_ID: Org-mode-Templates-A-reason-I-generate-templates
:END:
This produces a pop-up list of org-mode block types, if ~src~ is selected, then a
list of my commonly used languages pops-up. Alternatively, ignore the pop-up
menu and write any block or language name.
#+begin_src org :tangle "~/.emacs.d/yankpad.org" :comments none
,** begin: produce an org-mode block
,#+begin_${1:environment$(let*
((block '("src" "example" "quote" "verse" "center" "latex" "html" "ascii"))
(langs '("c" "emacs-lisp" "lisp" "latex" "python" "sh" "haskell" "plantuml" "prolog"))
(type (yas-choose-value block)))
(concat type (when (equal type "src") (concat " " (yas-choose-value langs)))))}
$0
,#+end_${1:$(car (split-string yas-text))}
#+end_src
In this case, ~yas-text~ is equivalent to (~yas-field-value 1)~;
it generally refers to the value of the field being mirrored with ~${n: ⋯yas-text⋯}~.
However, going through pop-ups takes precious time ---besides being slightly annyoing.
Let's introduce a template for my most utilised kind of language blocks.
#+begin_example
,** s_org: src block for org
,#+begin_src org
$0
,#+end_src
#+end_example
However, doing this for each language I want is a waste of time and textual
space. Why? *The purpose of templates is to reduce repetition,* yet the above
block would be repeated with only 3 parts ‘unknown’: The expansion keyword, the
description, and the org-mode source block name. Whence, the template /text/ is
generated by the following basic loop ---whose source block is named
~my-org-lang-templates~.
#+name: my-org-lang-templates
#+begin_src emacs-lisp :tangle no :wrap "src org :tangle ~/.emacs.d/yankpad.org" :exports code :results replace drawer
;; We make an org BLOCK snippet template for each LANG the user has declared.
;;
(cl-loop for (shortcut block takes-language-argument? default-text)
in '(("s_" "src" t)
("is_" "inline source" t) ;; Treated specially below
("e_" "example" t)
("q_" "quote")
("v_" "verse")
("c_" "center")
("ex_" "export") ;; only HTML and LATEX
;; https://alhassy.github.io/org-special-block-extras/#Summary
("p_" "parallel" nil "\n$0\n#+columnbreak:\n")
("d_" "details" nil "${1:title}\n$0")
("ed_" "edcomm" nil "${1:editor}\n$0")
("doc_" "documentation" nil "${1: mandatory entry name}\n$0")
("def_" "latex-definitions"))
for languages = (if takes-language-argument?
(-cons* "org" "agda2" "any" ;; Extra ‘languages’
;; Also include whatever languages we've loaded for literate programming.
(--map (symbol-name (car it)) org-babel-load-languages))
'("")) ;; The “empty language”
concat (cl-loop for lang in languages
for key = (concat shortcut
(if (s-blank? lang) block lang))
for description = (if (s-blank? lang)
block
(concat
block " for " lang))
concat (if (equal "is_" shortcut)
(concat "\n** " key ": " description
"\nsrc_" lang "[:exports code]{$1} $0")
(concat "\n** " key ": " description
"\n#+begin_" block " " lang
(or default-text "\n$0")
"\n#+end_" block "\n"))))
#+end_src
The /resulting text/ of this block, generated below, is tangled to our yankpad by
utilising a [[https://www.gnu.org/software/emacs/manual/html_node/org/Noweb-reference-syntax.html][noweb]] source block invocation. An example of the resulting text is
the above ~s_org~ block. The result is (last I checked) *83* template expansions
---that would have been a bit much to write by hand.
#+begin_example org
,#+begin_src org :tangle "~/.emacs.d/yankpad.org" :noweb yes
<>
,#+end_src
#+end_example
# ActuallyDoIt
#+begin_src org :tangle "~/.emacs.d/yankpad.org" :noweb yes :comments none
<>
#+end_src
# The “:eval never-export” means that this block is never tangled on document
# export, C-c C-e.
#+begin_box
Now ~s_~, due to company mode, brings up a list of languages that I can then
scroll down through, then “enter” upon to expand. Moreover, the prefix ~s_~ means
that the key is mostly irrelevant, since I needn't remember it because
company-mode immediately lists possible completions /along/ with the /descriptions/
for the snippets. Likewise for examples with ~e_~ or quotes with ~q_~. Super neat
stuff :-)
Ain't this reminiscent of meta-programming ;-)
#+end_box
Using =noweb= invocations, any time the tangling is performed, the yankpad
is kept up to date ---no personal intervention from myself.
# Neat, but not what I want.
# https://github.com/abo-abo/auto-yasnippet
:Fun_albeit_useless_exercise:
Let's push this frontier a bit more …
In expressive languages like Agda, one can not only be type polymorphic but also
‘level polymorphic’ ---since types constitute a hierarchy where a ‘type’ is
uninterestingly an ‘element’ of a higher ‘type’, ad infinitum. For example, the
type of a level polymorphic ′choice’ function would be ~{a : Level} (A : Set a) → A~
---note that such a choice function cannot exist since for any type ~A~ it returns
an element of ~A~, then what of the empty type. Anyhow, the template ~{${1:a} :
Level} → (${2:A} : Set $1) → $0~ would suffice to make this happen. Yet, what if
we wanted /n/-many sets?
Make a function that takes /n ≤ 26/ as input, produces a list of
levels, then uses each level to produce a list of type names ;-)
:End:
With the advent of org-special-block-extras, I've made increased usage of links
--such as ~green:hello~ which yields green:hello and ~[[kbd:][green]]~ which yields
[[kbd:][green]].
#+begin_src org :tangle "~/.emacs.d/yankpad.org" :comments none
,** ll_make_a_link: insert a link template
${1:`(let* ((τ (read-string "Link type: "))
(δ (read-string "Link Description: "))
(⊤ (if (s-contains? ":" τ) τ (s-concat τ ":"))))
(format "[[%s][%s]]" ⊤ δ))`} $0
#+END_SRC
*** Operating System Keyboard Symbols
:PROPERTIES:
:CUSTOM_ID: Operating-System-Keyboard-Symbols
:END:
Write ~os_~ then see a bunch of completions ;-)
#+name: my-snippets-os-symbols
#+begin_src emacs-lisp :tangle no :wrap "src org :tangle ~/.emacs.d/yankpad.org" :exports code :results replace drawer
(cl-loop for (name expansion)
in '((os-command ⌘)
(os_option ⌥)
(os_alt ⌥)
(os_control ⌃)
(os_shift ⇧)
(os_backspace ⌫)
(os_delete ⌫)
(os_delete_forward ⌦)
(os_enter ⏎)
(os_return ⏎)
(os_escape ⎋)
(os_tab_right ⇥)
(os_tab_left ⇤)
(os_caps_lock ⇪)
(os_eject ⏏))
concat
(format "** %s: %s Operating System Keyboard Symbol\n%s\n" name expansion expansion))
#+end_src
#+begin_src org :tangle "~/.emacs.d/yankpad.org" :noweb yes :comments none
<>
#+end_src
*** Work Templates
:PROPERTIES:
:CUSTOM_ID: Work-Templates
:END:
#+begin_src org :tangle "~/.emacs.d/yankpad.org" :comments none
,** ll_console_log: Log some JS variables
console.log("%c ******* LOOK HERE *******", "color: green; font-weight: bold;");
console.log({ ${1:List the variables here whose values you want to log} });
$0
,** uuidgen: Insert the result of “uuidgen” and copy it to the clipboard
${1:`(-let [it (shell-command-to-string "uuidgen | tr '[:upper:]' '[:lower:]' |
pbcopy; pbpaste")] (message "Copied to clipboard, uuid: %s" it) it)`}
#+end_src
*** Elisp Templates
:PROPERTIES:
:CUSTOM_ID: Elisp-Templates
:END:
The following snippets were rather useful as I began learning Lisp to construct
my editor of choice ---I love Emacs so much. Admittedly, I still need the first
one below and usually beat around the bush by using ~(cl-loop for ⋯ do ⋯)~, (doc:cl-loop), which is
‘noisier’ but easier to remember and to read for non-Lispers.
#+begin_src org :tangle "~/.emacs.d/yankpad.org" :comments none
,** loop: Elisp's for each loop
(dolist (${1:var} ${2:list-form})
${3:body})
,** defun: Lisp functions
(cl-defun ${1:fun-name} (${2:arguments})
"${3:documentation}"
$0)
,** cond: Elisp conditionals
(cond (${1:scenario₁} ${2:response₁})
(${3:scenario₂} ${4:response₂}))
#+end_src
*** Equational Templates
:PROPERTIES:
:CUSTOM_ID: Equational-Templates
:END:
To show ~ℒ = ℛ~, one starts at the complicated side, say /ℒ/, then, with the aim of
simplification, tries to end at the simpler side, /𝓡/. Along the way, one
justifies each step of the calculation. This approach is popular in the proof
assistant Agda; [[https://alhassy.github.io/PathCat/][Examples]]. Read more about [[http://www.mathmeth.com/][informal calculational proofs]].
#+begin_src org :tangle "~/.emacs.d/yankpad.org" :comments none
,** fun: Function declaration with type signature
${1:fun-name} : ${2:arguments}
$1 ${3:args} = ?$0
,** eqn_begin: Start a ≡-Reasoning block in Agda
begin
${1:complicated-side}
$0≡⟨ ${3:reason-for-the-equality} ⟩
${2:simpler-side}
∎
,** eqn_step: Insert a step in a ≡-Reasoning block in Agda
≡⟨ ${2:reason-for-the-equality} ⟩
${1:new-expression}
$0
#+end_src
One expands ~eqn_begin~, tabs to fill in the three main locations, then
/immediately/ types ~eqn_step~ to produce a new step in a calculational proof.
*** Fixed replies
:PROPERTIES:
:CUSTOM_ID: Fixed-replies
:END:
Here are some replies that I sometimes need to produce; e.g., to people who
insist their way is the right way.
#+begin_src org :tangle "~/.emacs.d/yankpad.org" :comments none
,** reply_opinionated_pantomath: What to say to, e.g., an arrogant academic
Your certainty inspires me to continuing exploring, and I may arrive at your
point of view, but I'm going to need more evidence first.
,** reply_em_dashes: Why use em dashes for parenthetical remarks?
According to the “Canadian Style Guide” (CSG):
The em is an expansive, attention-seeking dash. It supplies much stronger
emphasis than the comma, colon or semicolon it often replaces. Positioned
around interrupting elements, em dashes have the opposite effect of
parentheses—em dashes emphasize; parentheses minimize.
From “A Logical Approach to Discrete Math” (LADM), page ix:
We place a space on one side of an em dash ---here are examples--- in
order to help the reader determine whether the em dash begins or ends
a parenthetical remark. In effect, we are creating two symbols from one.
In longer sentences---and we do write long sentences from time to time---the
lack of space can make it difficult to see the sentence structure---especially
if the em dash is used too often in one sentence. Parenthetical remarks
delimited by parentheses (like this one) have a space on one side of each
parenthesis, so why not parenthetical remarks delimited by em dashes?
Interestingly, according to the CSG, there should be no space before or after an
em dash. As such, it appears that the spacing is mostly stylistic; e.g., some
people surround em-s with spaces on both sides. In particular, when em-s are
unmatched, I make no use of additional space ---indeed this form of one-sided
parentheses without a space is how LADM is written, as can be seen at the top of
page 3.
#+end_src
*** Misc Templates
:PROPERTIES:
:CUSTOM_ID: Misc-Templates
:END:
#+begin_src org :tangle "~/.emacs.d/yankpad.org" :comments none
,** remark: top-level literate comment
{{{remark(${1:thoughts})}}} $0
#+end_src
Where my local use contains ~#+MACRO: remark @@latex: \fbox{\textbf{Comment: $1 }}@@~.
*** Emojis :Disabled:
:PROPERTIES:
:CUSTOM_ID: emojis
:END:
#+NAME: my-emoji-templates
#+begin_src emacs-lisp :tangle nil :wrap "src org :tangle ~/.emacs.d/yankpad.org" :exports code :results replace drawer
;;
;; https://emojipedia.org/people/
(cl-loop for (emoji name description)
in '((😀 "Grinning Face"
"Often conveys general pleasure and good cheer or humor.")
(😃 "Grinning Face with Big Eyes"
"Often conveys general happiness and good-natured amusement.
Similar to 😀 Grinning Face but with taller,
more excited eyes.")
(😄 "Grinning Face with Smiling Eyes"
"Often conveys general happiness and good-natured amusement.
Similar to 😀 Grinning Face and 😃 Grinning
Face With Big Eyes, but with warmer, less
excited eyes.")
(😁 "Beaming Face with Smiling Eyes"
"Often expresses a radiant, gratified
happiness. Tone varies, including warm, silly,
amused, or proud.")
(😆 "Grinning Squinting Face"
"Often conveys excitement or hearty laughter.
Similar to 😀 Grinning Face but with eyes that
might say ‘Squee!’ or ‘Awesome!’ An emoji form of
the >< or xD emoticons.")
(😅 "Grinning Face with Sweat"
"Intended to depict nerves or discomfort but
commonly used to express a close call, as if
saying ‘Whew!’ and wiping sweat from the
forehead. ")
(🤣 "Rolling on the Floor Laughing"
"Often conveys hysterical laughter more intense
than 😂 Face With Tears of Joy.")
(😂 "Face with Tears of Joy")
(🙂 "Slightly Smiling Face")
(🙃 "Upside-Down Face")
(😉 "Winking Face")
(😊 "Smiling Face with Smiling Eyes")
(😇 "Smiling Face with Halo")
(🥰 "Smiling Face with Hearts")
(😍 "Smiling Face with Heart-Eyes")
(🤩 "Star-Struck")
(😘 "Face Blowing a Kiss")
(😗 "Kissing Face")
(☺️ "Smiling Face")
(😚 "Kissing Face with Closed Eyes")
(😙 "Kissing Face with Smiling Eyes")
(🥲 "Smiling Face with Tear")
(😋 "Face Savoring Food")
(😛 "Face with Tongue")
(😜 "Winking Face with Tongue")
(🤪 "Zany Face")
(😝 "Squinting Face with Tongue")
(🤑 "Money-Mouth Face")
(🤗 "Hugging Face")
(🤭 "Face with Hand Over Mouth")
(🤫 "Shushing Face")
(🤔 "Thinking Face")
(🤐 "Zipper-Mouth Face")
(🤨 "Face with Raised Eyebrow")
(😐 "Neutral Face")
(😑 "Expressionless Face")
(😶 "Face Without Mouth")
(😏 "Smirking Face")
(😒 "Unamused Face")
(🙄 "Face with Rolling Eyes")
(😬 "Grimacing Face")
(🤥 "Lying Face")
(😌 "Relieved Face")
(😔 "Pensive Face")
(😪 "Sleepy Face")
(🤤 "Drooling Face")
("Sleeping Face")
(😷 "Face with Medical Mask")
(🤒 "Face with Thermometer")
(🤕 "Face with Head-Bandage")
(🤢 "Nauseated Face")
(🤮 "Face Vomiting")
(🤧 "Sneezing Face")
(🥵 "Hot Face")
(🥶 "Cold Face")
(🥴 "Woozy Face")
(😵 "Dizzy Face")
(🤯 "Exploding Head")
(🤠 "Cowboy Hat Face")
(🥳 "Partying Face")
(🥸 "Disguised Face")
(😎 "Smiling Face with Sunglasses")
(🤓 "Nerd Face")
(🧐 "Face with Monocle")
(😕 "Confused Face")
(😟 "Worried Face")
(🙁 "Slightly Frowning Face")
(☹️ "Frowning Face")
(😮 "Face with Open Mouth")
(😯 "Hushed Face")
(😲 "Astonished Face")
(😳 "Flushed Face")
(🥺 "Pleading Face")
(😦 "Frowning Face with Open Mouth")
(😧 "Anguished Face")
(😨 "Fearful Face")
(😰 "Anxious Face with Sweat")
(😥 "Sad but Relieved Face")
(😢 "Crying Face")
(😭 "Loudly Crying Face")
(😱 "Face Screaming in Fear")
(😖 "Confounded Face")
(😣 "Persevering Face")
(😞 "Disappointed Face")
(😓 "Downcast Face with Sweat")
(😩 "Weary Face")
(😫 "Tired Face")
(🥱 "Yawning Face")
(😤 "Face with Steam From Nose")
(😡 "Pouting Face")
(😠 "Angry Face")
(🤬 "Face with Symbols on Mouth")
)
for nom = (s-replace " " "_" name)
for desc = (s-collapse-whitespace (or description ""))
concat (concat
;; f_… ⇒ get emoji from company menu showing only name & emoji
(format "\n** f_%s: %s %s \n%s" nom emoji "" emoji)
;; fd_… ⇒ get emoji from company menu showing name, emoji, & ‘d’escription
(format "\n** fd_%s: %s %s \n%s" nom emoji desc emoji)))
#+end_src
#+begin_src emacs-lisp
;; Get all unicode emojis to appear within Emacs
;; See also: https://emacs.stackexchange.com/questions/5689/force-a-single-font-for-all-unicode-glyphs?rq=1
;; (unless noninteractive (set-fontset-font t nil "Apple Color Emoji"))
#+end_src
#+begin_src org :tangle "~/.emacs.d/yankpad.org" :noweb yes :exports none
<>
#+end_src
##
*** =my_⋯= Templates to obtain User Information
:PROPERTIES:
:CUSTOM_ID: my-Templates-to-obtain-User-Information
:END:
Let's add templates for links to common user information ^_^
#+begin_src org :tangle "~/.emacs.d/yankpad.org" :comments none
,** my_name: User's name
`user-full-name`
,** my_email: User's email address
`user-mail-address`
,** my_github: User's Github repoistory link
https://github.com/alhassy/
,** my_emacsdrepo: User's version controlled Emacs init file
https://github.com/alhassy/emacs.d
,** my_blog: User's blog website
https://alhassy.github.io/
,** my_webpage: User's organisation website
http://www.cas.mcmaster.ca/~alhassm/
,** my_twitter: User's Twitter profile
https://twitter.com/musa314
,** my_masters_thesis
A Mechanisation of Internal Galois Connections In Order Theory Formalised Without Meets
https://macsphere.mcmaster.ca/bitstream/11375/17276/2/thesis.pdf
#+end_src
It may be useful to also have Org-link variants of these …
*** Templates from other places in my init
:PROPERTIES:
:CUSTOM_ID: Activate-templates-from-other-places-in-my-init
:END:
In this setup, I have some templates appear elsewhere, tagged with =:noweb-ref
templates-from-other-places-in-my-init=. They are presented in natural
positions, but can only occur to the machine after template expansion is setup.
Using org-mode, we are able to /present/ code in any order and /tangle/ it to
the order the compilers need it to be!
Let's activate all such templates, now after template expansion has been setup.
#+begin_src org :tangle no
,#+begin_src org :noweb yes :tangle "~/.emacs.d/yankpad.org" :comments none
<>
,#+end_src
#+end_src
You can press kbd:C-c_C-v_C-v, doc:org-babel-expand-src-block, to see what this
block expands into...
#+begin_details Expansion
# This is also live.
#+begin_src org :noweb yes :tangle "~/.emacs.d/yankpad.org" :comments none
<>
#+end_src
#+end_details
Note: Since I've insisted that Org blocks are space sensative, any whitespace
before the ~<<⋯>>~ will propogate to the resulting extracted code.
#+begin_box Warning! :background-color red
This section had
#+begin_src org :tangle no
:PROPERTIES:
:CUSTOM_ID: Templates-from-other-places-in-my-init
:END:
#+end_src
Which, as of Org 9.4, led to the entire section being tangled: This is what the
above incantation requested, but I thought it only worked on src blocks, having
the specified ~:noweb-ref~, not on ~:CUSTOM_ID:~ incidentally having the same
name.
#+end_box
** Executing all =#+name: startup-code= for local configurations :Disabled:I_have_not_used_this_in_some_time:
:PROPERTIES:
:CUSTOM_ID: Executing-all-name-startup-code-for-local-configurations
:header-args: :tangle no
:END:
Sometimes my Org-files contain configurations that are local to the file,
so I name all such =src= blocks =#+name: startup-code= and place =# -*- eval: (my/execute-startup-blocks) -*-= at the top of the file so that such
blocks are evaluated when the file opens up.
- The =-*- ... -*-= notation is for making local configurations.
- Use =M-x add-file-local-variable-prop-line= to have them inserted interactively.
#+begin_src emacs-lisp
(defun my/execute-startup-blocks ()
"Execute all startup blocks, those named ‘startup-code’.
I could not use ORG-BABEL-GOTO-NAMED-SRC-BLOCK since it only goes
to the first source block with the given name, whereas I'd like to
visit all blocks with such a name."
(interactive)
(save-excursion
(goto-char 0)
(while (ignore-errors (re-search-forward "^\\#\\+name: startup-code"))
(org-babel-execute-src-block))))
#+end_src
The following setup enables this feature in a safe fashion ---e.g., we do not
want to avoid evaluating a random person's potentially dangerous code when we
only want to look at it.
#+BEGIN_SRC emacs-lisp
;; Please ask me on a file by file basis whether its local variables are ‘safe’
;; or not. Use ‘!’ to mark them as permanently ‘safe’ to avoid being queried
;; again for the same file.
(setq enable-local-variables t)
#+END_SRC
I have been using a combination of =(org-babel-goto-named-src-block ⋯)= in
multi-line local-variable declarations ---=M-x add-file-local-variable-prop=---
for a while in many files using a dedicated =* footer :noexport:= section, but
this new approach frees from having such sections and instead to having a single
line at the top of the file. Moreover, being at the top of the file, such a line
is a nice *[[green:‘in your face’]]* reminder that there is local configuration that
should have been loaded.
# - E.g., this init file has local configuration for making the corresponding
# =init.el= file and generating the =README.org= file.
** Drag Stuff :Disabled:
:PROPERTIES:
:CUSTOM_ID: Drag-Stuff
:header-args: :tangle no
:END:
#+begin_src emacs-lisp
;; Move current word ←/→, or current line ↑/↓.
;; Todo: Compare with org-metaup and org-metadown...
(use-package drag-stuff
:config (cl-loop for (key . action) in '(("" . drag-stuff-down)
("" . drag-stuff-up)
("" . drag-stuff-right)
("" . drag-stuff-left))
do (bind-key key action org-mode-map))
(drag-stuff-global-mode 1))
#+end_src
Ruins Org-mode's M-↑/↓ for moving entire sections around.
** Prettify inline source code :Disabled:I_have_not_used_this_in_some_time:
:PROPERTIES:
:CUSTOM_ID: Prettify-inline-source-code
:header-args: :tangle no
:END:
#+begin_src emacs-lisp
;; Show “ src_emacs-lisp[:exports results]{ 𝒳 } ” as “ ℰ𝓁𝒾𝓈𝓅﴾ 𝒳 ﴿ ”.
;;
(font-lock-add-keywords 'org-mode
'(("\\(src_emacs-lisp\\[.*]{\\)\\([^}]*\\)\\(}\\)"
(1 '(face (:inherit (bold) :foreground "gray65") display "ℰ𝓁𝒾𝓈𝓅﴾"))
(2 '(face (:foreground "blue")))
(3 '(face (:inherit (bold) :foreground "gray65") display "﴿"))
)))
;;
;; Let's do this for all my languages:
;; Show “ src_LANGUAGE[…]{ ⋯ } ” as “ ﴾ ⋯ ﴿ ”.
(cl-loop for lang in my/programming-languages
do (font-lock-add-keywords 'org-mode
`(( ,(format "\\(src_%s\\[.*]{\\)\\([^}]*\\)\\(}\\)" lang)
(1 '(face (:inherit (bold) :foreground "gray65") display "﴾"))
(2 '(face (:foreground "blue")))
(3 '(face (:inherit (bold) :foreground "gray65") display "﴿"))
))))
;;
(defun my/toggle-line-fontification ()
"Toggle the fontification of the current line"
(interactive)
(defvar my/toggle-fontify/current-line -1)
(defvar my/toggle-fontify/on? nil)
(add-to-list 'font-lock-extra-managed-props 'display)
(let ((start (line-beginning-position)) (end (line-end-position)))
(cond
;; Are we toggling the current line?
((= (line-number-at-pos) my/toggle-fontify/current-line)
(if my/toggle-fontify/on?
(font-lock-fontify-region start end)
(font-lock-unfontify-region start end))
(setq my/toggle-fontify/on? (not my/toggle-fontify/on?)))
;; Nope, we've moved on to another line.
(:otherwise
(setq my/toggle-fontify/current-line (line-number-at-pos)
my/toggle-fontify/on? :yes_please_fontify)
(font-lock-unfontify-region start end)))))
;; TODO FIXME; maybe ignore: Wasted too much time here already.
;; (add-hook 'post-command-hook #'my/toggle-line-fontification nil t)
;; (font-lock-add-keywords nil '((my/toggle-line-fontification)) t)
#+end_src
** Compile :posterity:I_have_not_used_this_in_some_time:
:PROPERTIES:
:CUSTOM_ID: Compile
:header-args: :tangle no
:END:
Emacs' [[https://www.emacswiki.org/emacs/CompileCommand][compile]] command allows us to execute arbitrary Elisp
when ~M-x recompile~ is invoked. One of my habits is to append
most of my files with the
#+begin_src org :tangle no
# Local Variables:
# eval: (message "Load file specific stuffs here")
# compile-command: (async-shell-command (concat "open " (org-latex-export-to-pdf)))
# End:
#+end_src
Since nearly every file I work with is ─or can be coerced into being─ in org mode,
I usually have a section ~* footer~ that contains something like the above.
Let's remove repeated matter.
#+begin_src emacs-lisp :tangle no :tangle no
;; Silently save before compiling.
(setq compilation-ask-about-save nil)
;; Silently kill previous compilation process before starting a new one.
(setq compilation-always-kill t)
;; Scroll as compilation output is procuded in *Compilation* buffer; e.g., pdflatex
;; Use 'first-error to stop scrolling on the first error encountered; otherwise ‘t’.
(setq compilation-scroll-output 'first-error)
;; Don't stop on informaiton messages or warnings; only on errors.
(setq compilation-skip-threshold 2)
#+end_src
#+begin_src emacs-lisp :tangle no :tangle no
;; My global compile command
(setq compile-command
'(async-shell-command (concat "open " (org-latex-export-to-pdf))))
;; Bind ‘recompile’ to ‘C-c C-m’ ─“m” for “m”ake
(global-set-key (kbd "C-c C-m") 'recompile)
;; Also a helpful quick f-key.
(global-set-key (kbd "") 'recompile)
#+END_SRC
* Lisp Programming
:PROPERTIES:
:CUSTOM_ID: Lisp-Programming
:END:
** C-x C-e ∷ REPL-driven development for ELisp
:PROPERTIES:
:CUSTOM_ID: C-x-C-e-REPL-driven-development-for-NodeJS
:END:
| /Evaluate code and see the results inline ---A feedback loop that is faster than ever!/ |
Within Emacs, kbd:C-x_C-e evaluates a Lisp expression /anywhere/; e.g.,
at the end of ~(message-box "hello world")~ press ~C-x C-e~ to see a greeting.
# Likewise, evaluating a variable shows you its value: user-full-name.
- We ran some code /without/ explicitly running an interpreter/repl/compiler!
- This is known as “REPL driven development” (RDD):
There is a running REPL server for your language, implicitly in the
background, and your editor (say with ~C-x C-e~) will send it a line (or a
selected region) of code for evaluation; we then see the result as an
overlay in our current buffer.
+ You /choose/ which code gets (re)evaluated.
- A quick introduction to RDD can be viewed at
https://alhassy.com/repl-driven-development, including setup for other
languages.
*** ELisp :ignore:
:PROPERTIES:
:CUSTOM_ID: ELisp
:END:
By default, Emacs Lisp's kbd:C-x_C-e shows results only in the minibuffer; near
the bottom of the screen. Let's also have evaluation results displayed as inline
overlays ---at the location that the user, us, is actually looking/working;
rather than forcing their eyes to shift up&down when writing&evaluating.
+ kbd:C-u_C-x_C-e inserts the evaluation result at point; kbd:C-u_0_C-x_C-e does
so /without truncating/ lengthy output.
+ Read this [[https://karthinks.com/software/an-elisp-editing-tip/][Sweet & short blog/GIFs]] on practical uses of kbd:C-x_C-e when working with Lisp.
#+begin_src emacs-lisp
;; Evaluation Result OverlayS for Emacs Lisp
(use-package eros :init (eros-mode t))
#+end_src
# In particular, this gives us the Lisp function
# `eros--eval-overlay', which evaluates its argument X
# and produces an overlay of the result at position P.
# E.g., (eros--eval-overlay "hola" (point-min))
# Shows a momentary overlay at the first line.
*** COMMENT JavaScript :Disabled:
:PROPERTIES:
:CUSTOM_ID: JavaScript
:END:
In any JS file, I just press ~C-x C-e~ and the JS interpreter is brought up with the evaluation results shown:
For instance,
#+begin_src js :tangle no
// On each line and press C-x C-j
let a = "hello"
let b = "world"
(a + ' ' + b).toUpperCase()
// The final line should show: HELLO WORLD
#+end_src
**** COMMENT Preserving the context
:PROPERTIES:
:CUSTOM_ID: Preserving-the-context
:END:
When testing an application, you might notice a bug in a particular context
---i.e., a particular configuration in the app.
1. The classic approach is to kill the app; i.e., stop the server that is, well,
serving the app.
2. Solve the problem.
3. Try to get back to the configuration, context, you were in beforehand and
check that the problem has been resolved.
A better approach is to ignore the bookkeeping steps, 1&3, and just do step 2.
For that, there are numerous packages:
- [[https://github.com/mishoo/livenode/][livenode: Live-code your NodeJS applications]] ⨾⨾ [[https://vimeo.com/60636079][Video demo]] ~11min ⨾⨾ Last
updated 2013
- [[https://github.com/skeeto/skewer-mode][skewer-mode: Live web development in Emacs]] ⨾⨾ [[https://www.youtube.com/watch?v=4tyTgyzUJqM&ab_channel=Skeeto][Silent video demo]] ~5min ⨾⨾ Last
updated 2020
- [[https://github.com/swank-js/swank-js][swank-js: Swank backend for Node.JS and in-browser JavaScript]] ⨾⨾ Last updated
2015
For more RDD alternatives in Emacs, see https://github.com/anonimitoraf/skerrick/issues/8.
*** COMMENT TODO RDD.el for Java
**** get the pkg :ignore:
#+begin_src emacs-lisp :tangle init.el
(use-package repl-driven-development)
;; TODO: rdd.el should (require ⋯) the following!
(use-package json-navigator)
(use-package ansi-color)
(setq repl-driven-development-echo-duration 10)
#+end_src
**** terminal
#+begin_src emacs-lisp :tangle init.el
;; Sometimes I see a bunch of shell incantations in a README or something and I'd like to execute them right there and then,
;; and not have to bother with copying them over to a terminal and execute there. As such, here's a quick key binding to execute
;; shell commands from anywhere.
;; (repl-driven-development [C-x C-t] "bash" :prompt "bash-3.2\\$")
(repl-driven-development [C-x C-t] terminal)
#+end_src
**** jshell
#+begin_src emacs-lisp :tangle init.el
;; TODO: Changes to be pushed to master rdd.el ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
;; new
(defun repl-driven-development--main-callback (repl)
"Return the callback that works on REPL."
`(lambda (process output)
;; This is done to provide a richer, friendlier, interaction.
;; ^M at the end of line in Emacs is indicating a carriage return (\r)
;; followed by a line feed (\n).
(setq output (repl-driven-development--ignore-ansi-color-codes output)) ;; ⟵ ⟵ Main change here ⟵ ⟵ ⟵ ⟵ ⟵ ⟵ ⟵ ⟵
;; (message-box "%s" output)
(setq output (s-trim (s-replace-regexp ,(rdd@ repl prompt) ""
(s-replace "\r\n" "" output))))
;; Output is always non-empty
(unless (s-blank? (s-trim output))
(setf (rdd@ (quote ,repl) output) output))
(repl-driven-development--insert-or-echo (quote ,repl) output)))
;; Notice that I've changed :prompt!
(defun repl-driven-development-preconfiguration:java (keys)
""
(repl-driven-development
keys
;; enable assertions, and add everything installed, via `mvn', in scope.
(format "jshell --class-path %s --enable-preview -R -ea --feedback silent"
(concat ".:" (shell-command-to-string "find ~/.m2/repository -name \"*.jar\" -type f 2>/dev/null | tr '\n' ':'")))
:name 'java-eval
:prompt "[^\\n]*=>\\.\\.\\.\\." ;; ⟵ ⟵ Main change here ⟵ ⟵ ⟵ ⟵ ⟵ ⟵ ⟵ ⟵ ⟵ ⟵ ⟵ ⟵ ⟵ ⟵ ⟵ ⟵ ⟵ ⟵
:input-rewrite-fn
#'repl-driven-development--strip-out-C-style-comments&newlines
:init "/set mode EmacsJavaMode normal -command
/set format EmacsJavaMode display \"{pre}added import {name}{post}\" import-added
/set format EmacsJavaMode display \"{pre}re-added import {name}{post}\" import-modified,replaced
/set format EmacsJavaMode result \"{type} {name} = {value}{post}\" added,modified,replaced-primary-ok
/set truncation EmacsJavaMode 40000
/set feedback EmacsJavaMode
import javax.swing.*;
System.out.println(\"Enjoy Java with Emacs (｡◕‿◕｡))\")")
(defalias 'java-eval-read #'repl-driven-development--java-read))
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
;; Set “Cx Cj” to evaluate Java code in a background REPL.
(repl-driven-development [C-x C-j] java)
#+end_src
**** TODO COMMENT mvn
#+begin_src emacs-lisp :tangle init.el
(defun mvn (groupId artifactId)
"Quickly install a library from Maven Central."
(async-shell-command (format "mvn org.apache.maven.plugins:maven-dependency-plugin:2.8:get -Dartifact=%s:%s:LATEST:jar:sources" groupId artifactId)))
(when nil
⨾⨾ Example use of `mvn`
;; ⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾
;; First confirm C-x C-j works as intended
IntStream.range(0, 15).mapToObj(i -> i % 15 == 0 ? "FizzBuzz" : i % 3 == 0 ? "Fizz" : i % 5 == 0 ? "Buzz" : String.valueOf(i)).toList()
;; ⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾
(mvn "org.antlr" "antlr4") ;; C-x C-e
;; Now re-start the Java C-x C-j repl via a C-x C-e (lame! not ergonomic!)
;; Now check that you have access to antrl in your repl by importing it and looking at one of its classes:
;; ⦃ jshell --class-path /Users/musa/.m2/repository/org/antlr/antlr4-runtime/4.13.0/antlr4-runtime-4.13.0.jar ⦄
import org.antlr.v4.runtime.*;
CommonTokenStream.class
;; NOTE: This is the runtime, to use the actual tool:
java -jar /Users/musa/.m2/repository/org/antlr/antlr4/4.13.0/antlr4-4.13.0-complete.jar
;; Alternatively,
;; $ jshell
;; > var x = 5
;; > import org.antlr.v4.runtime.*; // CRASHES since antlr is not in scope
;; > /reset --class-path /Users/musa/.m2/repository/org/antlr/antlr4-runtime/4.13.0/antlr4-runtime-4.13.0.jar
;; > import org.antlr.v4.runtime.*; // WORKS, yay
;; > x // CRASHES, not in scope
;; ⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾
import org.apache.commons.lang3.StringUtils;
StringUtils.class;
/imports // JShell command to list all imports, it now contains apache!
// Guava is the Google core libraries for Java
import com.google.common.collect.ImmutableMap;
ImmutableMap.of(1, "A", 2, "B") // ⇒ {1=A, 2=B}
;; (mvn "com.google.code.gson" "gson")
// Then C-x C-e to update the repl definition of C-x C-j to include the updated gson library.
import com.google.gson.*;
String json = new Gson().toJson(Map.of("me", List.of(1, 2,3), "you", Map.of("Love", "Lisp", "Hate", "Verbosity")))
;; ⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾
;; TestNG is a testing framework; supporting tests configured by annotations, data-driven testing, parametric tests, etc.
(mvn "org.testng" "testng")
import org.testng.*;
/imports // Now can see org.testng at the end of the list
;; ⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾
;; TODO[Low]: For working with Lombok annotations, use the jshell `/reset --class-path` command to include the lombok compiled file into
;; the current Jshell session.
;;
;; See: https://stackoverflow.com/questions/74084364/how-to-use-lombok-in-jshell
;;
;; (mvn "org.projectlombok" "lombok")
;; import lombok.*;
;; @lombok.Data class Test { private String name; }
;; new Test().equals(new Test())
)
#+end_src
**** TODO COMMENT Adding support for “//!use” & “//!omit” top level repl commands
#+begin_src emacs-lisp
;; Adding support for “//!use” & “//!omit” top level repl commands
(setq repl/jshell/classpath (shell-command-to-string "find ~/.m2/repository -name \"*.jar\" -type f | tr '\n' ':'"))
(advice-add 'repl/jshell
:around (lambda (repl &rest args)
(if (equal nil current-prefix-arg)
;; No prefix supplied
(progn
(setq rdd---current-input (s-replace-regexp "\n" "" (s-trim-left
(if (region-active-p) (buffer-substring-no-properties (region-beginning) (region-end))
(substring-no-properties (thing-at-point 'line))))))
(if (s-starts-with? "//!use" rdd---current-input)
(-let [jar (s-trim (s-chop-prefix "//!use" rdd---current-input))]
(repl/top-level//!use jar))
(if (s-starts-with? "//!omit" rdd---current-input)
(-let [jar (s-trim (s-chop-prefix "//!omit" rdd---current-input))]
(repl/top-level//!omit jar))
;; otherwise business as usual
(apply repl args))))
(pcase current-prefix-arg
(-1
;; reset classpath to default, then business as usual.
(setq repl/jshell/classpath (shell-command-to-string "find ~/.m2/repository -name \"*.jar\" -type f | tr '\n' ':'"))
(apply repl args))
(999
(message-box "It worked"))
;; otherwise business as usual
(t (apply repl args))))))
;; remove all advice
;; (-let [sym 'repl/jshell] (advice-mapc (lambda (advice _props) (advice-remove sym advice)) sym))
(cl-defun repl/top-level//!omit (str)
(with-temp-buffer
(setq repl/jshell/classpath (s-replace-regexp (format ":[^:]*%s[^:]*:" str) ":" repl/jshell/classpath))
(insert "/env --class-path ")
(insert repl/jshell/classpath)
(repl/jshell (point-min) (point-max))))
(cl-defun repl/top-level//!use (str)
"If the given jar cannot be added successful, the existing classpath remains untouched.
Return to your default classpath by invoking the repl with the -1 prefix.
Example usage:
//!use ~/path/to/compiled/java/classes
import com.x.y.z;
Where directory hierarchy com/x/y/z denotes a Java package under the above //!use path.
"
(with-temp-buffer
(setq repl/jshell/classpath (concat (s-trim str) ":" repl/jshell/classpath))
(insert "/env --class-path ")
(insert repl/jshell/classpath)
(repl/jshell (point-min) (point-max))))
#+end_src
**** TODO COMMENT Misc top level cmds
TODO: Make repl load all company class files, that way I have them upon start up.
OR: Provide a command `//!load ~/dir` which recursively loads/imports all java files? <---Probably this!
**** TODO COMMENT Quickly Run Code Snippets
:PROPERTIES:
:CUSTOM_ID: Quickly-Run-Code-Snippets
:END:
Sometimes we want to quickly run some code /without making a dedicated file/ or
with a file but /without remembering the terminal incantation to do so/, enter
~quickrun~. Anywhere, we can select a snippet of code and run TODO. doc.quickrun-region
to execute that snippet after selecting the associated programming language, or
TODO. doc.quickrun-replace-region if we want the results in-line. If our language of
choice does not exist, we can [[https://github.com/emacsorphanage/quickrun#user-defined-command][easily add support for it]].
#+begin_src emacs-lisp
;; In any programming buffer, “M-x quickrun” to execute that program.
;; Super useful when wanting to quickly test things out, in a playground.
;;
;; E.g., Make a new file named “hello.py” containing “print "hi"”, then “M-x quickrun”.
;;
;; Enable “quickrun-autorun-mode” to run code after every save.
(use-package quickrun
;; ⇒ “C-c C-r” to see output, “q” to close output
;; ⇒ “C-u C-c C-r” prompts for a language (Useful when testing snippets different from current programming mode)
;; ⇒ In a non-programming buffer, “C-c C-r” runs selected region.
:config (bind-key* "C-c C-r"
(lambda (&optional start end)
(interactive "r")
(if (use-region-p)
(quickrun-region start end)
(quickrun current-prefix-arg)))))
#+end_src
Example...
#+begin_src emacs-lisp
(system-packages-ensure "rust") ;; Rust Compiler
;; Select the following then press C-c C-r: fn main() { println!("Hello, World!"); }
#+end_src
Actually, let's get a [[https://github.com/brotzeit/rustic#intro][full Rust development environment for Emacs]] (which also
has [[https://github.com/brotzeit/rustic#org-babel][great support for Org-babel]].)
#+begin_src emacs-lisp :tangle no
(use-package rustic)
;; Open any Rust file, and run “M-x lsp” which will then prompt you to install
;; rust-analyzer, the rust LSP.
;;
;; LSP for Rust ⇒ Goto definition (M-. / ⌘-l), code completion with types and
;; docstrings, colourful documentation on hover, “Run [Test] | Debug” overlays,
;; super nice stuff! Run “M-!”/[M-x company-show-doc-buffer] if you want the doc in a colourful buffer.
;;
;; Below, hover over “Vec” and see nice, scrollable, colourful docs on vectors.
;; let v:Vec<_> = vec![1, 2, 3];
;; The offical Rust toolchain installer
(system-packages-ensure "rustup")
(shell-command "rustup update")
#+end_src
:More_on_rust:
Now, C-c C-c C-d on something to get help/description of it.
(setq rustic-racer-rust-src-path "/Users/musa/.rustup/toolchains/stable-x86_64-apple-darwin/lib/rustlib/src/rust/library/")
# Get Rustup, load it into current terminal session
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
source ~/.bash_profile
source ~/.bashrc
type rustup
# Get stuff
rustup update
rustup component add rust-src
cargo +nightly install racer
rustup toolchain install nightly
rustup component add rustc-dev --toolchain=nightly
cargo +nightly install racer
:End:
** ⌘-e: Edit Everything in a separate buffer
:PROPERTIES:
:CUSTOM_ID: e-Edit-Everything-in-a-separate-buffer
:END:
Edit comment/string/docstring/code block in separate buffer with your favourite
mode.
+ ⌘-e to toggle “e”diting of thing at point.
+ ⌘-e will try to edit thing at point, or selection, if possible; otherwise it
will exit edit session.
- 🔥 Avoid escape nightmares by editing strings in a separate buffer.
- On a string, press ⌘-e and a new buffer pops up with unescaped content,
letting you edit raw strings directly. It then takes care of automatically
escaping strings for you when you press ⌘-e, or ~C-c C-c~ ---or discard your
changes with ~C-c C-k~.
+ ⌘-e can be used within edit session to create new edit sessions, if possible; then ⌘-e will “pop-off-the-stack” as expected.
- (I already use ⌘-e to toggle editing Org src blocks, and when editing a block ⌘-e will try to do a recursive edit if possible, or exit the edit session.)
- (The separedit package also let's me press ⌘-e to edit variable values when describing them, and to edit text when in the minibuffer.)
From [[https://github.com/twlz0ne/separedit.el][source]]:
#+begin_example org
+----------+ Edit +-----------+ Edit +-----------+
| | ---------------------> | edit | ---------------------> | edit | ...
| | point-at-comment? | buffer | point-at-comment? | buffer |
| source | point-at-string? | | point-at-string? | | ...
| buffer | point-at-codeblock? | (markdown | point-at-codeblock? | (markdown | ...
| | point-at-...? | orgmode | point-at-...? | orgmode |
| | <--------------------- | ...) | <--------------------- | ...) | ...
+----------+ Commit changes +-----------+ Commit changes +-----------+
#+end_example
[In-general, we can invoke [[https://github.com/Fanael/edit-indirect/blob/e3d86416bcf8ddca951d7d112e57ad30c5f9a081/edit-indirect.el#L124][M-x edit-indirect-region]] to edit any selected piece
of text in its own buffer, then ~C-c C-c~ (or ~⌘-e~ with my setup) to commit the
edit. Actually, I've altered by ~⌘-e~ setup to also account for a selected region
😉]
#+begin_src emacs-lisp
(use-package separedit)
;;
;; # Example Usage
;;
;; 1. Press ⌘-e on this line, to edit this entire comment.
;; 2. Press ⌘-e to exit the edit session.
;;
;; Since my ⌘-e is context sensitive, to determine whether to continue editing or
;; exit; you can explicitly request an edit with C-c ' and an exit with C-c C-c.
;;
;; ```
;; ;; 3. Press ⌘-e on this line, to edit this source block!
;; ;; 4. Press ⌘-e on this line, to edit this inner-most comment!
;; ;; 5. At start of next line, press “⌘-r ⌘-e” to edit just the source block
;; ;;
;; (cl-defun index (&rest args)
;; "6. Press ⌘-e to edit this string, \"7. and again in these quotes\""
;; "
folds away all code indented 4 spaces, whereas is for 8
spaces, and disables the folding. This is built into Emacs.
I've incorporated this into my folding hydra, below.
#+end_box
#+begin_box "Vimish fold - Fold regions based on selection, not syntax"
Sometimes we want to fold some random piece of text ---rather than fold accoding
to a programming language's syntactic constructions.
[[https://github.com/mrkkrp/vimish-fold][Vimish-fold]] gives us just that and with many fancy features, from the README:
+ folding of active regions;
+ good visual feedback: it's obvious which part of text is folded with a ‘⋮’ in the fringe.
+ create folds from regions between ~{{{~ and ~}}}~ automatically (marks are customizable; TODO. doc.vimish-fold-from-marks);
+ persistence by default: when you kill a buffer your folds don't disappear;
+ persistence scales well, you can work on hundreds of files with lots of folds without adverse effects;
+ it does not break indentation;
+ folds can be toggled from folded state to unfolded and back very easily;
+ quick navigation between existing folds;
+ you can use mouse to unfold folds (good for beginners and not only for them).
#+begin_src emacs-lisp
(use-package vimish-fold
:hook (after-init . vimish-fold-global-mode))
#+end_src
#+end_box
*** COMMENT TODO Actual Setup :ignore:
:PROPERTIES:
:CUSTOM_ID: Actual-Setup
:END:
--------------------------------------------------------------------------------
TODO: Below I setup hideshow along with [doc : hideshowvis-symbols] [hideshowvis] which gives us a nice clickable
“+/-” marker for foldable blocks as well as an overlay that indicates how many
lines are folded away. For more on hideshow-mode, see the [[https://writequit.org/denver-emacs/presentations/2017-11-02-hidden-gems.html][Hidden Gem Packages]]
presentation which contains a small self-contained introduction, or [[https://github.com/emacs-mirror/emacs/blob/master/lisp/progmodes/hideshow.el#L127][these super useful source comments]]
which discuss hooks and support for special modes ([[https://superuser.com/questions/576447/enable-hideshow-for-more-modes-e-g-ruby][like this one]]).
#+BEGIN_SRC emacs-lisp
;; https://www.gnu.org/software/emacs/manual/html_node/emacs/Hideshow.html
(use-package hideshow
;; Press “C-c TAB” to toggle a block's visibility or “C-c f” for my folding hydra.
:bind ("C-c TAB" . hs-toggle-hiding)
;; https://github.com/shanecelis/hideshow-org/tree/master
;; This extension bring Org-mode tab behaviour to folding, at the block level
;; and buffer level ---but not cycling visibility.
;; (use-package hideshow-org) ;; Disabled as commented below.
:hook (prog-mode . (lambda () (hs-minor-mode +1)
(hideshowvis-minor-mode t)
(hideshowvis-symbols)
;; This hook along with hs-org mode breaks editing of src blocks in Org files.
;; That's OK, since my folding hydra does a better job for my needs.
;; (hs-org/minor-mode t)
(hs-hide-all))))
#+END_SRC
Along with a hydra for super quick navigation and easily folding, unfolding
blocks! Love this one (•̀ᴗ•́)و
#+BEGIN_SRC emacs-lisp
(my/defhydra "C-c f" "Folding text" archive
:Current
("h" hs-hide-block "Hide")
("s" hs-show-block "Show")
("t" hs-toggle-hiding "Toggle")
;; "l" hs-hide-level "Hide blocks n levels below this block"; TODO: Enable folding feature
:Buffer
("H" hs-hide-all "Hide")
("S" hs-show-all "Show")
("T" my/hs-toggle-buffer "Toggle")
:Style
("i" my/clever-selective-display "Fold along current indentation" :toggle selective-display)
("e" my/auto-set-selective-display-mode "Explore; walk and see" :toggle t)
:Region
("f" (lambda () (interactive) (vimish-fold-toggle) (vimish-fold (region-beginning) (region-end))) "Fold/Toggle")
("d" vimish-fold-delete "Delete fold")
("U" vimish-fold-unfold-all "Unfold all")
("D" vimish-fold-delete-all "Delete all")
("n" vimish-fold-next-fold "Next fold")
("p" vimish-fold-previous-fold "Previous fold")
:...
("w" hl-todo-occur "Show WIPs/TODOs" :exit t)
("m" lsp-ui-imenu "Menu of TLIs" :exit t) ;; TLI ≈ Top Level Items
;; ("i" imenu-list "iMenu (General)") ;; It seems the above is enough for both prog and otherwise.
("r" (progn (hs-minor-mode -1) (hs-minor-mode +1)) "Reset Hideshow") ;; Remove all folds from the buffer and reset all hideshow-mode. Useful if it messes up!
("q" nil "Quit" :color blue))
;; Features from origami/yafolding that maybe I'd like to implement include:
;; narrowing to block or folding everything except block, navigating back and forth between folded blocks.
;; Finally, if we want to cycle the visibility of a block (as in Org-mode), we can use a combination of hs-show-block and hs-hide-level.
#+END_SRC
#+begin_details "Folding Hydra Helpers"
#+BEGIN_SRC emacs-lisp
(defvar my/hs-hide nil "Current state of hideshow for toggling all.")
(defun my/hs-toggle-buffer () "Toggle hideshow all."
(interactive)
(setq my/hs-hide (not my/hs-hide))
(if my/hs-hide
(hs-hide-all)
(hs-show-all)))
#+END_SRC
#+BEGIN_SRC emacs-lisp
(defun my/clever-selective-display (&optional level)
"Fold text indented same of more than the cursor.
This function toggles folding according to the level of
indentation at point. It's convenient not having to specify a
number nor move point to the desired column.
"
(interactive "P")
(if (eq selective-display (1+ (current-column)))
(set-selective-display 0)
(set-selective-display (or level (1+ (current-column))))))
#+END_SRC
#+BEGIN_SRC emacs-lisp
;; Src: https://emacs.stackexchange.com/questions/52588/dynamically-hide-lines-indented-more-than-current-line
(define-minor-mode my/auto-set-selective-display-mode
"Automatically apply `set-selective-display' at all times based on current indentation."
nil "$" nil
(if auto-set-selective-display-mode
(add-hook 'post-command-hook #'auto-set-selective-display nil t)
(remove-hook 'post-command-hook #'auto-set-selective-display t)
(with-temp-message ""
(set-selective-display nil))))
;;
(defun my/auto-set-selective-display ()
"Apply `set-selective-display' such that current and next line are visible.
Scroll events are excluded in order to prevent wild flickering while navigating."
(unless (eq last-command #'mwheel-scroll)
(let*((this-line-indent (current-indentation))
(next-line-indent (save-excursion (forward-line) (current-indentation))))
(with-temp-message "" ; Suppress messages.
(set-selective-display (1+ (max this-line-indent next-line-indent)))))))
#+END_SRC
#+end_details
# TODO: MA: With the switch to helm-occur, is the following still required?
#
# With expected support for searching.
# #+BEGIN_SRC emacs-lisp
# ;; Open folded nodes if a search stops there.
# (add-hook 'helm-swoop-after-goto-line-action-hook #'my/search-hook-function)
# (defun my/search-hook-function ()
# (when hs-minor-mode (set-mark-command nil) (hs-show-block) (pop-to-mark-command)))
# #+END_SRC
#+begin_details "What if I want my own hideshow overlays, instead of hideshowvis?"
#+BEGIN_SRC emacs-lisp :tangle no
;; Add an overlay to display the number of hidden lines 😁;; https://github.com/shanecelis/hideshow-org/tree/master
(setq hs-set-up-overlay
(defun my-display-code-line-counts (ov)
(when (eq 'code (overlay-get ov 'hs))
(overlay-put ov 'display
(propertize
(format " ... ﴾%d﴿"
(count-lines (overlay-start ov)
(overlay-end ov)))
'face 'font-lock-type-face)))))
#+END_SRC
#+end_details
#+begin_details "[Disabled / Alternative] origami"
#+BEGIN_SRC emacs-lisp :tangle no
(use-package origami
;; In Lisp languages, by default only function definitions are folded.
;; :hook ((agda2-mode lisp-mode c-mode) . origami-mode)
;; Please open any code with top level items folded away.
:hook (prog-mode . (lambda () (interactive)
(origami-close-all-nodes (current-buffer))))
;; MA: It seems that this is not ideal; it takes a bit longer than I'd like to fold the whole file.
:config
;; For any major-mode that doesn't have explicit support, origami will use the
;; indentation of the buffer to determine folds.
(global-origami-mode)
;; With basic support for one of my languages.
(push '(agda2-mode . (origami-markers-parser "{-" "-}"))
origami-parser-alist))
#+END_SRC
With expected support for searching.
#+BEGIN_SRC emacs-lisp :tangle no
(defun my/search-hook-function ()
(when origami-mode (origami-open-node-recursively (current-buffer) (point))))
;; Open folded nodes if a search stops there.
(add-hook 'helm-swoop-after-goto-line-action-hook #'my/search-hook-function)
;;
;; Likewise for incremental search, isearch, users.
;; (add-hook 'isearch-mode-end-hook #'my/search-hook-function)
#+END_SRC
And hydra...
#+BEGIN_SRC emacs-lisp :tangle no
(my/defhydra "C-c f" "Folding text" archive
:Current
("h" origami-close-node-recursively "Hide")
("s" origami-open-node-recursively "Show")
("c" origami-recursively-toggle-node "Cycle") ;; Acts like org-mode header collapsing. Cycle a fold between open, recursively open, closed.
("f" origami-show-only-node "Focus") ;; Close everything but the folds necessary to see the point. Very useful for concentrating on an area of code.
;; ("H" origami-close-all-nodes "Hide All")
;; ("S" origami-open-all-nodes "Show All")
:Navigate
("n" origami-next-fold "Next")
("p" origami-previous-fold "Previous")
:...
("t" origami-toggle-all-nodes "Toggle buffer")
("m" lsp-ui-imenu "Menu of TLIs" :exit t) ;; TLI ≈ Top Level Items
;; ("i" imenu-list "iMenu (General)") ;; It seems the above is enough for both prog and otherwise.
("r" origami-reset)) ;; Remove all folds from the buffer and reset all origami state. Useful if origami messes up!
#+END_SRC
# *Disabled:* I've looked at a few folding modes, and I like this one.
# However, I seldom need it.
#+end_details
#+begin_details "[Disabled / Alternative] yafolding"
I found using yafolding-mode to be way too slow.
#+begin_src emacs-lisp :tangle no
;; “Yet Another Folding” just works: Indented elements are folded away; no setup required.
;; (use-package discover)
(use-package yafolding
;; Please open any code with top level items folded away:
;; Open the file super quick, but when I'm inactive for 5 seconds,
;; then I'm probably doing other stuff so do the folding then.
;; :hook prog-mode . (lambda () (interactive)
;; (run-with-idle-timer 5 nil #'yafolding-hide-all))
;; MA: It seems that this is not ideal; it takes a bit longer than I'd like to fold the whole file.
)
(defhydra yafolding-hydra (:color pink :columns 3)
"Fold code based on indentation levels"
;; First row
("s" yafolding-show-element "show element")
("S" yafolding-show-all "show all")
("" (lambda () (interactive)
(let ((next (car (yafolding-get-overlays (point) (point-max)))) pos)
(if (not next) (message "No more folded regions")
(setq pos (overlay-start next))
(yafolding-hide-element)
(goto-char pos)
(yafolding-show-element))))
"forward element")
;; Second row
("h" yafolding-hide-element "hide element")
("H" yafolding-hide-all "hide all")
("" (lambda () (interactive)
(let ((previous (car (yafolding-get-overlays (point-min) (point)))) pos)
(if (not previous) (message "No more folded regions")
(setq pos (overlay-start previous))
(yafolding-hide-element)
(goto-char pos)
(yafolding-show-element))))
"backward element")
;; Third row
("SPC" yafolding-toggle-element "toggle element")
("T" yafolding-toggle-all "toggle all")
("q" nil "quit" :color red)
("p" yafolding-hide-parent-element "hide parent")
("" (lambda () (interactive) (or (ignore-errors (yafolding-go-parent-element))
(message "Already at the top level.")))
"go to parent")
("r" (lambda () (interactive) (yafolding-hide-region (region-beginning) (region-end)))
"hide region"
))
(global-set-key (kbd "s-f") 'yafolding-hydra/body)
#+end_src
#+end_details
*** E2E Test :ignore:
:PROPERTIES:
:CUSTOM_ID: E2E-Test
:END:
#+begin_details Test
#+begin_src emacs-lisp :tangle init-test.el
(ert-deftest hideshow-is-enabled-and-folds-by-default ()
:tags '(hideshow)
;; Make a temporary scratch.js file with the given contents.
(let* ((contents "function fierce(name) { \n return `${name}: ROAR` \n }")
(scratch.js (make-temp-file "scratch" nil ".js" contents)))
;; Hideshow is enabled whenever we open a code file
(find-file scratch.js)
(should hs-minor-mode)
;; Function definition is a hidden block
(end-of-line)
(backward-char 2)
(should (hs-already-hidden-p))
;; Indeed, the hidden block starts at the first line break and ends just after the second.
(-let [ov (hs-already-hidden-p)]
(-let [(first\n second\n) (-elem-indices "\n" (s-split "" contents))]
(should (equal (overlay-start ov) first\n)) ;; ≈ 25
(should (equal (overlay-end ov) (+ second\n 2))))) ;; ≈ 52
(kill-buffer)))
#+end_src
#+end_details
** Aggressive Indentation
:PROPERTIES:
:CUSTOM_ID: Aggressive-Indentation
:END:
With a single space or tab, my code should always remain indented.
[[https://github.com/Malabarba/aggressive-indent-mode][aggressive-indent-mode]] is a minor mode that keeps your code always indented. It
reindents after every change, making it more reliable than electric-indent-mode.
#+BEGIN_SRC emacs-lisp
;; Always stay indented: Automatically have blocks reindented after every change.
(use-package aggressive-indent
:hook (after-init . global-aggressive-indent-mode))
;; Use 4 spaces in places of tabs when indenting.
(setq-default indent-tabs-mode nil)
(setq-default tab-width 4)
#+END_SRC
This mode requires my Lisp forms to be well-balanced; e.g., having a missing
parenthesis does not indent. For instance, I have a form ~F~ and I write ~(when F~
but have not yet enclosed the final parens, I still want nice indentation. So...
*** [[https://github.com/jiahaowork/el-fly-indent-mode.el][Indent Emacs Lisp on the fly]] :Disabled:Breaks_C_c_C_v_C_t:
:PROPERTIES:
:CUSTOM_ID: https-github-com-jiahaowork-el-fly-indent-mode-el-Indent-Emacs-Lisp-on-the-fly
:header-args: :tangle no
:END:
#+begin_src emacs-lisp :tangle no
;; This minor mode toggles on along with elisp-mode and indents on the fly when
;; you edit the code. No special key strokes needed.
;; Demo: https://www.youtube.com/watch?v=zrFmfFZfj-A&ab_channel=JiahaoLi
(use-package el-fly-indent-mode
:config (add-hook 'emacs-lisp-mode-hook #'el-fly-indent-mode))
#+end_src
*** Indentation Guide
:PROPERTIES:
:CUSTOM_ID: Indentation-Guide
:END:
The following is also “OK” in Org-mode ;-)
#+begin_src emacs-lisp
;; Add a visual indent guide
(use-package highlight-indent-guides
:hook (prog-mode . highlight-indent-guides-mode)
:custom
(highlight-indent-guides-method 'character)
(highlight-indent-guides-character ?|)
(highlight-indent-guides-responsive 'stack))
#+end_src
*** Being Generous with Whitespace :Disabled:
:PROPERTIES:
:CUSTOM_ID: Being-Generous-with-Whitespace
:END:
| Disabled: I'm not actively writing C-like code in Emacs. |
The following minor mode automatically adds spacing around operators.
#+begin_src emacs-lisp :tangle no
(use-package electric-operator
:hook (c-mode . electric-operator-mode))
#+end_src
I dislike it when users write ~x=y+1~ ---whitespace is free and helpful. ⟨ Also,
languages with arbitrary identifiers, like Lisp and Agda, would accept ~x=y+1~ as
an identifier, not an expression! ⟩
*** Auto-format on Save :Disabled:
:PROPERTIES:
:CUSTOM_ID: Auto-format-on-Save
:header-args: :tangle no
:END:
| Disabled: I mainly code in ELisp and so don't require this utility. |
# ! :Breaks_HTML_export_of_org_files_with_unicode_or_emojis:
[[https://github.com/lassik/emacs-format-all-the-code/tree/eb2a7fa6da15d23b57921218a36ac67d523e81f1][Auto-format source code in many languages with one command]]
Let's auto-format source code in many languages using the same command for all
languages, instead of learning a different Emacs package and formatting command
for each language.
Just do ~M-x format-all-buffer~ and it will try its best to do the right thing. To
auto-format code on save, use the minor mode format-all-mode. Better yet, we ask
for it to do so “on save”.
- You will need to install external programs to do the formatting. If
~format-all-buffer~ can't find the right program, it will try to tell you how to
install it.
- An alternative Emacs tool is [[https://github.com/radian-software/apheleia][apheleia: 🌷 Run code formatter on buffer
contents without moving point, using RCS patches and dynamic programming.]]
#+begin_src emacs-lisp
(use-package format-all
;; To enable format on save for most programming language buffers:
:hook (prog-mode . format-all-mode)
:config
;; Please use the default formatters; I don't care too much.
(add-hook 'format-all-mode-hook 'format-all-ensure-formatter))
#+end_src
[[https://prettier.io/docs/en/index.html][Prettier]] is an opinionated code formatter for numerous web related languages,
including JS, TS, HTML, CSS, JSON, Vue, Markdown, and YAML.
#+begin_src emacs-lisp
;; For JavaScript prettification: It automatically inserts semicolons, forces newlines, inserts parens, etc.
;; Lots of redundant stuff, but stuff to make it easy to work with others.
(shell-command "npm install --global prettier")
;; Specific package to do only JS prettification: https://github.com/prettier/prettier-emacs
#+end_src
For example, in a NodeJS app make a file ~.prettierrc.json~ whose contents are
#+begin_src json :tangle no
{
"singleQuote": true,
"arrowParens": "avoid",
"printWidth": 120,
"semi": false,
"trailingComma": "none"
}
#+end_src
Unfortunately, my current team prefers ~"semi": true~ ---which is understandable
for people not familar with how JavaScript does [[https://www.freecodecamp.org/news/lets-talk-about-semicolons-in-javascript-f1fe08ab4e53/][semicolon insertion]].
( If you're having trouble getting prettier to work on save, consider using this
[[https://github.com/codesuki/add-node-modules-path][package]] which detects your node modules' path. )
Anyhow, with these rules:
- I write =const f = (x) => "x" == x= then on save it becomes =const f = x => 'x' == x;=
- I write =let xs = [1, 2, 3,]= then on save it becomes =let xs = [1, 2, 3];=
- I write =foo(reallyLongArg(), omgSoManyParameters(), IShouldRefactorThis(), isThereSeriouslyAnotherOne());=
then nothing happens on save; but if you add one more argument, =, 12=, then it gets reformatted with each arg on one line.
Notice that in the first example above, only minor syntactic changes were made;
nothing altering semantics or quality of code ---for that, we use a /linter/.
In particular, [[https://emacs-lsp.github.io/lsp-mode/page/lsp-eslint/][LSP ESLint]] when activated will show us two errors: It's almost always
better to use ~===~ instead of ~==~ and literals should be on the right side of the equality.
We can use ~M-x lsp-execute-code-action~ to get a list of actions that can be performed to fix this /quality/ problem.
*** Which function are we writing?
:PROPERTIES:
:CUSTOM_ID: Which-function-are-we-writing
:END:
In the modeline, show the name of the function we're currently writing.
#+BEGIN_SRC emacs-lisp
(add-hook 'prog-mode-hook #'which-function-mode)
(add-hook 'org-mode-hook #'which-function-mode)
#+END_SRC
In Org-mode, this places the current heading in the modeline.
In Lisp mode, ensure we always have matching parens.
#+BEGIN_SRC emacs-lisp
(add-hook 'emacs-lisp-mode-hook #'check-parens)
#+END_SRC
** Semantic and Syntactic Highlighting
*** Coding with a Fruit Salad: Semantic Highlighting
:PROPERTIES:
:CUSTOM_ID: Coding-with-a-Fruit-Salad-Semantic-Highlighting
:END:
What should be highlighted when we write code? Static keywords with fixed uses,
or dynamic user-defined names?
+ /Syntax/ highlighting ⇨ Specific words are highlighted in strong colours so that
the /structure/ can be easily gleaned.
- Generally this only includes a language's keywords, such as ~if, loop, begin,
end, cond~.
- User defined names generally share one colour; usually black.
- Hence, an ~if~ block may be seen as one coloured keyword followed by
a blob of black text.
/Obvious keywords are highlighted while the rest remains in black!/
+ /Semantic/ highlighting ⇨ Identifiers obtain unique colouring.
- This makes it much easier to visually spot dependencies with a quick glance.
+ One can *see* how data flows through a function.
- In dynamic languages, this is a visual form of typing: Different colours are
for different names.
+ Especially helpful for (library) names that are almost the same.
+ This can be accomplished anywhere in Emacs by pressing ~M-s h .~ on
a selected phrase.
For Emacs, [[https://github.com/ankurdave/color-identifiers-mode][Color Identifiers Mode]] gives unique highlighting to identifiers.
- It comes with support for a bunch of languages, and one can add support for others.
- It picks colours adaptively to fit the theme; one uses ~M-x color-identifiers:regenerate-colors~ after a theme change.
#+begin_src emacs-lisp
(use-package color-identifiers-mode
:config (global-color-identifiers-mode))
;; Sometimes just invoke: M-x color-identifiers:refresh
#+END_SRC
When writing a new name, after about ~5 seconds it obtains a colour which is then
propagated immediately to any new occurrences. This timeout before recolouring
is to avoid any lag from multithreading and can be changed by altering the following
line (#64) in the source file, changing the ~5~ to a smaller number.
#+BEGIN_SRC emacs-lisp :tangle no
(run-with-idle-timer 5 t 'color-identifiers:refresh)
#+END_SRC
Here are further reads:
- [[https://medium.com/@evnbr/coding-in-color-3a6db2743a1e][Coding in color: How to make syntax highlighting more useful]] ---an excellent, terse, read
- [[https://zwabel.wordpress.com/2009/01/08/c-ide-evolution-from-syntax-highlighting-to-semantic-highlighting/][C++ IDE Evolution: From Syntax Highlighting to Semantic Highlighting]]
+ Names with a similar prefix share a colour, and class-local items share a colour.
- [[https://wordsandbuttons.online/lexical_differential_highlighting_instead_of_syntax_highlighting.html][Lexical differential highlighting instead of syntax highlighting]]
+ /Ideally, the smaller the lexical difference, the greater the color difference should be./
- [[https://github.com/jacksonrayhamilton/context-coloring][Colouring by Context]] ---an Emacs package
- [[http://www.linusakesson.net/programming/syntaxhighlighting/][A case against syntax highlighting]]
*** Highlight Quoted Symbols
:PROPERTIES:
:CUSTOM_ID: highlight-quoted-symbols
:END:
#+begin_src emacs-lisp
(use-package highlight-quoted
:config (add-hook 'emacs-lisp-mode-hook 'highlight-quoted-mode))
;; If everything worked fine, then “ 'b ” below should be coloured nicely in Emacs Lisp mode.
(when nil
(-let [x 'somevar]
(list x 'b "c" :e)))
#+end_src
*** Highlighting Numbers and Escape Characters
:PROPERTIES:
:CUSTOM_ID: Syntax-highlighting-numbers-and-escape-characters
:END:
Lightweight syntax highlighting improvement for numbers and escape sequences (e.g. \n, \t) /within/ quotes.
#+begin_src emacs-lisp
(use-package highlight-numbers
:hook (prog-mode separedit-double-quote-string-mode)) ;; The latter is for when I do ⌘-e on a quoted string to edit it.
(use-package highlight-escape-sequences
:hook ((prog-mode . hes-mode)
(separedit-double-quote-string-mode . hes-mode)) ;; Wont work since this mode has no font-lock-builtin-face
:config
;; Colour the escapes as if they were builtin keywords.
(put 'hes-escape-backslash-face 'face-alias 'font-lock-builtin-face)
(put 'hes-escape-sequence-face 'face-alias 'font-lock-builtin-face))
;; TODO: My Emacs seems to have trouble loading the following and so I'm doint it manually.
(load-file "~/.emacs.d/elpa/highlight-escape-sequences-20201214.1730/highlight-escape-sequences.el")
(load-file "~/.emacs.d/elpa/parent-mode-20240210.1906/parent-mode.el")
(load-file "~/.emacs.d/elpa/highlight-numbers-20181013.1744/highlight-numbers.el")
;; If the above two worked fine, then you should see \n and 3 highlighted below
(when nil "Look: 1 and \\ and \n 2" (setq three 3))
#+end_src
*** Highlight /defined/ Lisp symbols
:PROPERTIES:
:CUSTOM_ID: Highlight-defined-Lisp-symbols
:END:
Usually Emacs only highlights macro names, the [[https://github.com/Fanael/highlight-defined][following]] incantation makes it
highlight all defined names ---as long as we're in Lisp mode, whence in org-src
blocks we use ~C-c '~.
#+BEGIN_SRC emacs-lisp
;; Emacs Lisp specific
(use-package highlight-defined :hook emacs-lisp-mode)
(load-file "~/.emacs.d/elpa/highlight-defined-20210411.222/highlight-defined.el")
#+END_SRC
Super helpful in making my Emacs configuration: If a name is not highlighted,
then I've misspelled it or it doesn't exist! :smile:
** show-me :Disabled:
#+begin_src emacs-lisp :tangle no :results replace
(defun show-me ()
"Evaluate a Lisp expression and insert its value
as a comment at the end of the line.
Useful for documenting values or checking values.
"
(interactive)
(-let [it
(thread-last (thing-at-point 'line)
read-from-string
car
eval
(format " ;; ⇒ %s"))]
(end-of-line)
(insert it)))
#+END_SRC
** Smartparens :Disabled:
#+begin_src emacs-lisp :tangle no
(use-package smartparens
:init
(smartparens-global-mode 1)
(show-smartparens-global-mode +1)
:bind (
("M-f" . sp-forward-sexp) ;; Move forward one expression.
("M-b" . sp-backward-sexp) ;; Move backward one expression.
;; Going to the start & end of current expr in pair-able character.
("M-a" . sp-beginning-of-sexp)
("M-e" . sp-end-of-sexp)
;; Going forwards deep down & up current expr; treating it as a tree.
("M-d" . sp-down-sexp)
("M-u" . sp-up-sexp)
;; Acending & descending backwards; i.e., leftwards.
("M-n" . sp-backward-down-sexp)
("M-p" . sp-backward-up-sexp)
;; Unwrapping: Removing pair-able characters.
("M-w" . sp-unwrap-sexp)
("M-m" . sp-backward-unwrap-sexp)
;; “Slurping”: Move closing character forward/backward to include next sexp.
;; “Barfing”: Contract a sexp, or string, by pushing a its last/first item out.
;; See below for examples.
("M-)" . sp-forward-slurp-sexp)
("M-(" . sp-backward-slurp-sexp)
("M-]" . sp-forward-barf-sexp)
("M-[" . sp-backward-barf-sexp)
;; Transpose two bracketed terms; e.g., a b c ⟪Here⟫ ⟶ a c b ⟪Here⟫
;; Transpose backwards by being on the token;
;; transpose forwards by being after the token.
("M-t" . sp-transpose-sexp)
)
:config
;; Enable smartparens everywhere
(use-package smartparens-config)
(setq
;; smartparens-strict-mode t
;; sp-autoinsert-if-followed-by-word t
;; sp-autoskip-closing-pair 'always
sp-hybrid-kill-entire-symbol nil)
;; In Elisp & org modes, do not ‘close’ a back-tick or single quote!
(sp-local-pair 'emacs-lisp-mode "`" nil :when '(sp-in-string-p))
(sp-local-pair 'emacs-lisp-mode "'" nil :when '(sp-in-string-p))
(sp-local-pair 'org-mode "`" nil :when '(sp-in-string-p))
(sp-local-pair 'org-mode "'" nil :when '(sp-in-string-p))
)
#+END_SRC
*Wrapping*
To enclose a token with a pair-able character, at the start of the expression
press ~C-ESCAPE-SPACE~, select the region, followed by a pair-able character such as ~[, {, ", ', *,~ etc.
To wrap a single token forwards, use ~C-M-SPACE~.
Examples of slurping & barfing --i.e., sexp inclusion and contraction.
#+begin_example
a [x y z] b ⟶“M-) inside [⋯]”⟶ a [x y z b]
a [x y z] b ⟶“M-) inside [⋯]”⟶ [a x y z] b
[a x y z b] ⟶“M-] inside [⋯]”⟶ a [x y z b]
[a x y z b] ⟶“M-] inside [⋯]”⟶ [a x y z] b
#+end_example
** Column Marker :Disabled:
:PROPERTIES:
:CUSTOM_ID: Column-Marker
:END:
Have a thin line to the right to ensure I don't write “off the page”.
#+begin_src emacs-lisp :tangle no :tangle no
(use-package fill-column-indicator
:hook (prog-mode . fci-mode))
;; (setq fill-column 120)
#+END_SRC
** interactive macro-expander
Anywhere in a macro form, press ~C-c e~ to start an (inline) interactive session
where you can see what the expanded form of the macro looks like and you can
move your cursor to other macro forms and expand those as well by pressing
~e~. Then press ~q~ to quit.
#+begin_src emacs-lisp
(use-package macrostep
:bind (:map emacs-lisp-mode-map ("C-c e" . macrostep-expand)))
#+end_src
This seems like an excellent way to debug macros.
** Smart jumping to definitions
# By default ~M-.~ only works on definitions that live in files: If you press ~C-x
# C-e~ at the end of ~(setq foo 1)~ then invoke ~M-.~ on “ foo ”
#+begin_src emacs-lisp
(😴 progn
(use-package elisp-def)
(bind-key* "M-." #'elisp-def emacs-lisp-mode-map)
;; Example usage:
(when nil
(let ((foo 1))
(setq foo 2))) ;; “M-.” on this “foo” will now take us to the start of the let-clause.
)
#+end_src
** Projectile: Project management & navigation :MostlyDisabled:
:PROPERTIES:
:CUSTOM_ID: Project-management-navigation
:END:
Version controlled repositories are considered “projects” ---no setup needed---,
but you can declare your own too.
Videos:
+ ~5mins: https://youtu.be/bFS0V_4YfhY
+ ~1hr: https://www.youtube.com/watch?v=INTu30BHZGk
This is so sweet at work (and possibly at home!): From anywhere,
+ [[kbd:C-x p p]] ⟨select your project⟩ RET ⟨start typing to see any file anywhere in the project⟩
+ [[kbd:C-x p b ]] ⇒ Switch to buffers only in the current “stream of thought” (project).
+ [[kbd:C-x p f ]] ⇒ Find files only in the current “stream of thought” (project).
+ [[kbd:C-x p s g ]] ⇒ Search the project using grep; TAB in the resulting buffer to
open files.
+ [[kbd:C-x p S ]] ⇒ Save all project buffers
+ [[kbd:C-x p k ]] ⇒ Kill all buffers relating to the parent project
+ [[kbd:C-x p & ]] ⇒ Runs an async-shell-command in the project's root directory
+ [[kbd:C-x p x s ]] ⇒ Start or visit a shell for the project
+ [[kbd:C-x p r ]] ⇒ Runs interactive query-replace on all files in the projects
+ [[kbd:C-x p e ]] ⇒ Show a list of recently visited files, in the current project
+ [[kbd:C-x p V ]] ⇒ Open a project that has been modified, but not pushed with version control.
/It can also jump to associated test files and run tests on a project./
#+begin_src emacs-lisp :tangle no
;; More info & key bindings: https://docs.projectile.mx/projectile/usage.html
(use-package projectile
:bind (("C-x p" . #'projectile-command-map)
;; Replace usual find-file with a project-wide version 😄
("C-x f" . #'projectile-find-file)
("C-x p c" . #'my/copy-current-file-path))
;; Makes indexing large projects much faster, after first time.
;; Since its caching, some files may be out of sync; you can delete the cache
;; with: C-u C-x f
:custom (projectile-enable-caching t)
:hook (after-init . projectile-mode))
;; “p”roject “s”earch
(define-key projectile-mode-map (kbd "C-x p s")
;; I prefer helm-do-grep-ag since it shows me a live search
(lambda () (interactive)
(let ((default-directory (car (projectile-get-project-directories (projectile-acquire-root)))))
;; (shell-command-to-string "echo $PWD")
(helm-do-grep-ag nil))))
#+end_src
*[Only Non-Disabled Part]*
Let's get the file path of the current file. We bind it and make it a top-level invokable function.
#+begin_src emacs-lisp :tangle init.el
(defun my/copy-current-file-path ()
"Add current file path to kill ring."
(interactive)
(kill-new buffer-file-name)
(message "Copied path “%s” to clipboard" buffer-file-name))
#+end_src
** Work Programming :Disabled:
:PROPERTIES:
:header-args: :tangle no
:END:
| /Disabled: At work I program in Java, and IntelliJ is better than Emacs out-of-the-box./ |
*** TODO Managing Processes/Servers from within Emacs ---Work-specific functions
:PROPERTIES:
:CUSTOM_ID: Managing-Processes-Servers-from-within-Emacs-Work-specific-functions
:END:
Let's make a few interactive Emacs Lisp functions to reduce the amount of time I
need to be in a terminal. I'll use the /prefix ~“w-”~ for work stuff/. Example
tasks:
+ Start/stop my servers
+ Interactively select an app to be opened in the browser
+ Do database migrations/rollbacks
⟨ Obfuscated with lorem ipsum text. ⟩
[[file:images/services-dashboard.png]]
--------------------------------------------------------------------------------
Not using this, a bit too verbose to setup for each service but, more
accurately, does not Just Workᵀᴹ for my needs.
#+begin_src emacs-lisp
;; “M-x prodigy”, then press “s” to start a service; “S” to stop it; “$” to see it; “r”estart
(use-package prodigy :disabled t)
;; C-h v prodigy-services ⇒ See possible properties.
#+end_src
**** my/defaliases
:PROPERTIES:
:CUSTOM_ID: my-defaliases
:END:
#+begin_src emacs-lisp
(defalias 'defaliases 'my/defaliases)
(defmacro my/defaliases (src &rest tgts)
"Provide names TGTS as synonymous aliases for SRC, for discovarability.
Often a function SRC can be construed from different perspectives, names, purposes TGTS.
Another example is when I define things with the ‘my/’ prefix, but also want to use them without.
Example use: (my/defaliases view-hello-file greet-others learn-about-the-world)
In particular: (my/defaliases OLD NEW) ≈ (defalias 'NEW 'OLD)."
`(--map (eval (quote (defalias `,it (quote ,src)))) (quote ,tgts)))
#+end_src
**** Making unkillable buffers & shells
:PROPERTIES:
:CUSTOM_ID: Making-unkillable-buffers-shells
:END:
#+begin_details "Making unkillable buffers & shells"
#+begin_src emacs-lisp
(defun my/declare-unkillable-buffer (name)
(add-hook 'kill-buffer-query-functions
`(lambda () (or (not (equal (buffer-name) ,name))
(progn (message "Not allowed to kill %s, burying instead; otherwise use “M-x force-kill”" (buffer-name))
(bury-buffer))))))
(my/defaliases my/force-kill force-kill w-force-kill)
(cl-defun my/force-kill (&optional buffer-name)
(interactive)
(-let [kill-buffer-query-functions nil]
(if buffer-name
(kill-buffer buffer-name)
(kill-current-buffer))
(ignore-errors (delete-window))))
(cl-defun my/run-unkillable-shell (command &optional (buffer-name command))
"Example use: (my/run-unkillable-shell \"cd ~/my-noejds-project; npm run dev\" \"my-nodejs-project\")"
(-let [it (get-buffer buffer-name)]
(if it
(switch-to-buffer-other-window it)
(async-shell-command command buffer-name)
(my/declare-unkillable-buffer buffer-name))))
#+end_src
#+end_details
**** w-start/stop-services
:PROPERTIES:
:CUSTOM_ID: w-start-stop-services
:END:
#+begin_src emacs-lisp
(defvar my/services nil "List of all services defined; used with `w-start-services' and `w-stop-services'.")
(defun w-start-services ()
(interactive)
(cl-loop for 𝑺 in my/services
do (funcall (intern (format "w-start-%s" 𝑺)))))
(defun w-stop-services ()
(interactive)
(cl-loop for 𝑺 in my/services
do (funcall (intern (format "w-stop-%s" 𝑺)))))
#+end_src
**** w-status-of-services
:PROPERTIES:
:CUSTOM_ID: w-status-of-services
:END:
#+begin_src emacs-lisp
;; It takes about ~3 seconds to build the Status of Services page, so let's jump to it if it's already built, and the user/me can request a refresh, if need be.
(global-set-key (kbd "M-S-SPC")
(lambda () (interactive)
(-let [buf (get-buffer "Status of Services")] (if buf (switch-to-buffer buf) (w-status-of-services)))))
;;
;; Since M-S-SPC brings up the transient menu, and most commands close the status buffer or are transient, we get the perception that the transient menu is "sticky"; i.e., stuck to the buffer, even though this is not true. I do not yet know how to make a transient menu stuck to a buffer.
;;
#+end_src
#+begin_src emacs-lisp
(defun w-status-of-services ()
"Show me status of all servers, including their current git branch, and most recent emitted output."
(interactive)
(defvar w-status-of-services/branch-name-width 12
"What is the length of the longest branch name? Let's use that to ensure there's enough whitespace.")
(-->
(-let [ shells (--filter (s-starts-with? "Shell" (process-name it)) (process-list)) ]
(cl-loop for 𝑺 in (mapcar #'pp-to-string my/services)
for associated-shell = (--find (s-contains? (format "%s" 𝑺) (cl-third (process-command it))) shells)
for status = (or (ignore-errors (process-status associated-shell)) '💥)
for branch = (-let [default-directory (format "~/%s" 𝑺)]
(magit-get-current-branch))
for _ = (setq w-status-of-services/branch-name-width (max (length branch) w-status-of-services/branch-name-width))
for 𝑺-buffer = (--find (s-starts-with? (format "*Server:%s" 𝑺) it) (mapcar 'buffer-name (buffer-list)))
for saying = (let (most-recent-shell-output (here (current-buffer)))
(if (not 𝑺-buffer)
" ─Server not started─ "
(switch-to-buffer 𝑺-buffer)
(end-of-buffer)
(beginning-of-line)
(setq most-recent-shell-output (or (thing-at-point 'line t) ""))
(switch-to-buffer here)
;; FIXME:here
(--> (s-truncate 135 (s-trim most-recent-shell-output))
(if (s-contains? "|" it)
(cl-second (s-split "|" it))
it)
(s-trim it)
(if (<= (length it) 3) (s-repeat 70 " ") it))))
for _ = (if (or (s-contains? "Error" saying) (not 𝑺-buffer)) (setq status '💥))
for keymap = (copy-keymap org-mouse-map)
do (cl-loop for (key action)
on `( ;; Checkout branch/PR
c (w-pr-checkout (format "~/%s" ,𝑺))
;; Restart service, remaining on current branch [not switching to “main”!]
r (-let [current-prefix-arg t]
(funcall (intern (format "w-stop-%s" ,𝑺)))
(funcall (intern (format "w-start-%s" ,𝑺))))
f (-let [default-directory (format "~/%s" ,𝑺)]
(call-interactively #' projectile-find-file))
t (vterm-shell-command (format "clear; cd ~/%s; git status" ,𝑺) (format "vterm/%s" ,𝑺))
;; See the repo in the web
w (--> (format "%s" ,𝑺)
(if (s-contains? "/" it) (f-parent it) it)
(format "https://github.com/%s/%s" work/gh-user it)
(browse-url it))
;; Visit service shell
(when ,𝑺-buffer
(delete-other-windows)
(split-window-below)
(switch-to-buffer ,𝑺-buffer)
(end-of-buffer)
(other-window 1))
;; See service magit buffer
(progn (magit-status (format "~/%s" ,𝑺)) (delete-other-windows)))
by #'cddr
do (define-key keymap (kbd (format "%s" key))
`(lambda () (interactive) ,action)))
collect
;; “%𝑾s” ⇒ Print a string with at least width 𝑾: If length(str) ≤ 𝑾, then pad with spaces on the left side.
;; Use “%-𝑾s” to instead pad with spaces to the right.
(list keymap (format (format "%%s %%-20s %%-%ss %%s" (+ 5 w-status-of-services/branch-name-width)) status 𝑺 branch saying))))
;; Setup buffer
(-let [buf "Status of Services"]
(ignore-errors (kill-buffer buf))
(switch-to-buffer buf)
(delete-other-windows)
it)
;; Insert out buttons
(--each it
;; https://www.gnu.org/software/emacs/manual/html_node/elisp/Overlay-Properties.html
(-let [help (s-join "\n"
'("Keybindings:"
"[C-u] c ∷ Checkout PR [or branch] \t\t\t b ∷ Browse an app"
"tab ∷ See service magit buffer \t\t\t i ∷ Inject users"
"return ∷ Visit service shell \t\t\t s ∷ SQL buffer"
"r ∷ Restart service \t\t\t w ∷ See the repo in the web"
"f ∷ Find file in project \t\t\t t ∷ Terminal"
"g ∷ Refresh this view \t\t\t q ∷ Quit, and kill, this buffer"))]
(insert-text-button (s-replace "\"" "″" (s-replace "run" "✅" (nth 1 it)))
'face nil
;; 'mouse-face '(:box t) ;; I use the cursor more than the mouse, so don't want two distinct views.
'keymap (nth 0 it)
;; NOTE: The functions are called only when the minor mode cursor-sensor-mode is turned on.
;; When cursor enters the button, we temporarily make it a box and show shortcuts in message area.
'cursor-sensor-functions `((lambda (_ old-pos entered?)
(message ,help)
(setq entered? (equal entered? 'entered))
(-let [self (button-at (if entered? (point) old-pos))]
(read-only-mode 0) ;; Temporarily disable help-mode's read-only-mode setup.
(if entered?
(button-put self 'face '(:box "yellow" :weight bold))
(button-put self 'face nil)))))
'help-echo help)
(insert "\n")))
;; Do some highlighting, as a cautionary measure.
(highlight-regexp ".*crashed.*" 'hi-red-b)
;; Forbid editing
(help-mode) ;; This wont do the button face changes I like when cursor moves; so I disable read-only-mode temporarily when making the changes.
(cursor-sensor-mode)
(stripe-buffer-mode)
(visual-line-mode -1)
(toggle-truncate-lines)
;; Add some specific work related bindings
(local-set-key "b" #'w-browse-app)
(local-set-key "i" #'w-inject-users)
(local-set-key "s" (lambda () (interactive) (w-sql) (delete-other-windows)))
;; Add general view keys
(local-set-key "g" (lambda () "Refresh this view" (interactive) (ignore-errors (kill-buffer-and-window)) (w-status-of-services)))
(local-set-key "q" (lambda () "Quit buffer" (interactive) (ignore-errors (kill-buffer-and-window))))
;; Go to the first entry, so my “homemade echo menu” appears.
(beginning-of-buffer)))
#+end_src
***** COMMENT Old definition with colourful menu :ignore:
:PROPERTIES:
:CUSTOM_ID: COMMENT-Old-definition-with-colourful-menu
:END:
#+begin_src emacs-lisp
(defun w-status-of-services ()
"Show me status of all servers, including their current git branch, and most recent emitted output."
(interactive)
(thread-last
(-let [ shells (--filter (s-starts-with? "Shell" (process-name it)) (process-list)) ]
(cl-loop for 𝑺 in (mapcar #'pp-to-string my/services)
for associated-shell = (--find (s-contains? (format "%s" 𝑺) (cl-third (process-command it))) shells)
for status = (or (ignore-errors (process-status associated-shell)) '💥)
for branch = (-let [default-directory (format "~/%s" 𝑺)]
(magit-get-current-branch))
for saying = (let (most-recent-shell-output (here (current-buffer)))
(switch-to-buffer (--find (s-starts-with-p 𝑺 (buffer-name it)) (buffer-list)))
(end-of-buffer)
(beginning-of-line)
(setq most-recent-shell-output (or (thing-at-point 'line t) ""))
(switch-to-buffer here)
(s-truncate 135 (s-trim most-recent-shell-output)))
collect
;; “%𝑾s” ⇒ Print a string with at least width 𝑾: If length(str) ≤ 𝑾, then pad with spaces on the left side.
;; Use “%-𝑾s” to instead pad with spaces to the right.
(format "%s %-20s %-12s %s" status 𝑺 branch
(-let [it (s-trim (if (s-contains? "|" saying)
(cl-second (s-split "|" saying))
saying))]
(if (<= (length it) 3) "-" it)))))
(--map (format "%s" it))
(s-join "\n")
(s-replace "run" "✅")
(funcall (lambda (it) (-let [max-mini-window-height 0]
(ignore-errors (kill-buffer "Status of Services"))
(display-message-or-buffer it "Status of Services")
(delete-other-windows)
(switch-to-buffer "Status of Services")
(highlight-regexp ".*crashed.*" 'hi-red-b)
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
;; Start describing the keys
(end-of-buffer)
(insert "\n \n \n \n \n")
(let ((register-action (lambda (key-desc-actions)
(if (stringp key-desc-actions)
(propertize key-desc-actions 'font-lock-face '(face success))
(-let [ [key desc &rest actions] key-desc-actions ]
;; For buffer-local keys, you cannot use local-set-key, unless you want to modify the keymap of the entire major-mode in question: local-set-key is local to a major-mode, not to a buffer.
;; (use-local-map (copy-keymap text-mode-map))
(local-set-key key `(lambda () (interactive) ,@(seq-into actions 'list)))
(format "%s %s"
(propertize (format "%s" key) 'font-lock-face '(face error))
(propertize desc 'font-lock-face '(:foreground "grey")))))))
(repo-at-point (lambda () (-as-> (beginning-of-line) repo
(thing-at-point 'line t)
(s-split " " repo)
cl-second))))
(insert (s-join "\n" (seq-mapn (lambda (&rest cols) (apply #'format (s-repeat (length cols) "%-40s ")
(--map (funcall register-action it) cols)))
["This view"
["g" "Refresh this view" (ignore-errors (kill-buffer-and-window)) (w-status-of-services)]
["q" "Quit buffer" (ignore-errors (kill-buffer-and-window))]
["" "" ""]]
`["Current service"
["c" "Checkout PR" (w-pr-checkout (format "~/%s" (funcall ,repo-at-point)))]
[[return] "Visit service shell"
(delete-other-windows)
(split-window-below)
(switch-to-buffer (--find (s-starts-with? (funcall ,repo-at-point) (buffer-name it)) (buffer-list)))
(end-of-buffer)
(other-window 1)]
[[tab] "See service magit buffer"
(magit-status (format "~/%s" (funcall ,repo-at-point)))
(delete-other-windows)]]
["Misc"
["b" "Browse an app" (w-browse-app)]
["i" "Inject users" (w-inject-users)]
["s" "SQL buffer" (w-sql) (delete-other-windows)]]))))
(beginning-of-buffer)
;; (help-mode) ;; For some reason, default fundamental-mode does not regoznise proprtised strings.
;; Also, this is read-only be default and emits a nice message for undefiend single key bindings.
;; (help-mode)
)))))
#+end_src
**** my/defservice
:PROPERTIES:
:CUSTOM_ID: my-defservice
:END:
#+begin_src emacs-lisp
;; Even though I'm doing frequent prunes, it helps to give docker some leeway.
;; NOTE: Docker Icon → Preferences → Resources → 4 CPUs; 8gb Memory; 2gb Swap; 120 DiskImageSize.
(cl-defmacro my/defservice
(repo &key (main-setup "git checkout main; git pull; git status; hr; npm ci; hr; time docker system prune -af")
(cmd "npm run docker:dev")
(example ""))
"Example use:
(my/defservice 𝒟 :cmd 𝒞 :example ℰ)
⇒
(w-start-𝒟) ≈ Unkillable shell: cd 𝒟; 𝒞
(w-is-up-𝒟?) ≈ Open browser at ℰ
(w-stop-𝒟) ≈ Kill all emacs-buffers & docker-images containing 𝒟 in their name
(w-[start|stop]-services) ⇒ Starts/stops all defined services."
(add-to-list 'my/services repo)
`(list
(cl-defun ,(intern (format "w-start-%s" repo)) ()
"Start server off of ‘main’, with prefix just start server off of current branch."
(interactive)
(let ((command (format "cd ~/%s; pwd; hr; %s; hr; %s"
(quote ,repo)
(if current-prefix-arg "" ,main-setup)
,cmd))
(buf-name (format "*Server:%s/%s*" (quote ,repo)
(if current-prefix-arg "main"
(-let [default-directory ,(format "~/%s" repo)]
(magit-get-current-branch))))))
(my/run-unkillable-shell
(format "echo %s; hr; %s" (pp-to-string command) command) ;; Show command being run in output buffer, then run that command
buf-name)
(with-current-buffer buf-name (read-only-mode))))
(cl-defun ,(intern (format "w-stop-%s" repo)) ()
"Force-kill all unkillable buffers that mention REPO in their name. Also stop any docker services mentioning REPO in their name."
(interactive)
(my/docker-stop ,(pp-to-string repo))
(thread-last (buffer-list)
(mapcar 'buffer-name)
(--filter (s-contains-p ,(pp-to-string repo) it))
(mapcar #'my/force-kill)))
(if ,example
(cl-defun ,(intern (format "w-is-up-%s?" repo)) ()
(interactive)
(browse-url ,example)
(message "If the URL is busted, then the repo is not up correctly or the server has an error!")))))
#+end_src
In my private ~work.el~ I have declarations of the form ~(my/defservice ⟨directory⟩
:cmd "npm run dev" :example "Example URL to try out for this server")~.
#+begin_src emacs-lisp
;; (when my/work-machine?
;; (load-file "~/Desktop/work.el"))
#+end_src
*** TODO See all company related PRs
:PROPERTIES:
:CUSTOM_ID: See-all-company-related-PRs
:END:
#+begin_src emacs-lisp
(cl-defun w-PRs (&rest query-options)
"See all company related PRs"
(interactive)
(thread-last `("is:open" "is:pr" "archived:false" "draft:false" ,@work/gh-tags ,@query-options)
(mapcar #'url-hexify-string)
(s-join "+")
(concat "https://github.com/pulls?q=")
browse-url))
;;
(cl-loop for (name . query-options)
in `((month ,(format-time-string "updated:>=%Y-%m-01"))
(today ,(format-time-string "updated:>=%Y-%m-%d"))
(created-this-week ,(format "created:>=%s"
(org-read-date nil nil "++1" nil (org-read-date nil t "-sun")))) ;; Date of most recent Monday
(stale!! ,(format "updated:<=%s" (org-read-date nil nil "-1w"))) ;; Items not touched in over a week
(mentions-me "mentions:alhassy") ;; i.e., stuff I need to look at
(involves-me "involves:alhassy")
(process-manager "label:\"quick and easy\"" "repo:process-builder")
(newts "label:\"Newts Priority Review\",Newts"))
do (eval `(cl-defun ,(intern (format "w-PRs-%s" name)) () (interactive) (w-PRs ,@query-options))))
#+end_src
**** TODO A nice Emacs interface for a portion of the “gh” CLI
:PROPERTIES:
:CUSTOM_ID: A-nice-Emacs-interface-for-a-portion-of-the-gh-CLI
:END:
#+begin_src emacs-lisp
;; A nice Emacs interface for the a portion of the “gh” CLI.
(my/defaliases my/gh-checkout gh-checkout w-pr-checkout w-branch-checkout)
(cl-defun my/gh-checkout (&optional repo)
"With prefix, select a branch name; otherwise a Pull Request name.
If no REPO is provided, let the user select one from a menu.
Example use: (w-pr-checkout \"~/my-repo\")
(w-pr-checkout)"
(interactive)
(let* ((repo (or repo (completing-read "Repo: " (projectile-relevant-known-projects))))
(default-directory repo) ;; temporarily override this global variable, used with magit
(current-branch (magit-get-current-branch))
(all-branches (magit-list-local-branch-names))
(status (format "cd %s; gh pr status" repo)))
(if current-prefix-arg
(-let [branch (completing-read (format "New branch (Currently “%s”): " current-branch) all-branches)]
(shell-command-to-string (format "cd %s; git checkout %s" repo branch)))
(let* ((PR-list (s-split "\n" (shell-command-to-string (format "cd %s; gh pr list" repo))))
(pr♯ (car (s-split "\t" (completing-read "PR: " PR-list))))
(_ (shell-command-to-string (format "cd %s; gh pr checkout %s" repo pr♯)))
(new-branch (magit-get-current-branch)))
;; Show nice status
(async-shell-command status)
(magit-status repo)))))
#+end_src
*** TODO SQL ---via LSP
:PROPERTIES:
:CUSTOM_ID: SQL-When-doing-serious-database-work-I-love-using-DBeaver-But-when-I-only
:END:
When doing ‘serious’ database work, I love using DBeaver. But when I only want
to /quickly/ run a query, to check something, *without the fricition of switching
applications*, then doing so in Emacs is a no-brainer: I use doc : w-sql to produce
a query buffer, if one doesn't exist, then ~C-c C-c~ to send queries. (This also
serves as a nice *reference mechanism* for useful queries.)
Let's use [[https://github.com/lighttiger2505/sqls][LSP for SQL]], to get
+ Neato tooltips on table definitions and column constraints,
- Write ~select * from my-table t~ then delete the ~*~ and enter ~t.~ to see all
valid columns; or just delete the ~*~ and press ~.~ to see them.
+ Completions for tables & column names,
+ ~C-c C-c~ to execute query at point [My personal setup below],
- TODO: Run all queries with doc : lsp-execute-code-action
+ TODO: When sharing with others, maybe execute doc : lsp-format-buffer
+ Note: The tokenizer is known to a bit buggy.
- E.g., ~select 1 + 2 as "Numerical, yeah!"~ will not be run due to the ‘!’.
#+begin_src emacs-lisp
;; Installation: go install github.com/lighttiger2505/sqls
(setq lsp-sqls-server "/Users/musa/go/bin/sqls")
(setq lsp-sqls-timeout 1)
(setq lsp-sqls-workspace-config-path nil)
;; https://emacs-lsp.github.io/lsp-mode/page/lsp-sqls/
(setq work/sqls-connections nil)(setq work/sqls-connections
'("host=127.0.0.1 port=5432 user=SUPER_SECRET password=ALSO_SUPER_SECRET dbname=YET_AGAIN_SECRET sslmode=disable"))
(setq lsp-sqls-connections
;; (--map `((driver . "postgresql") (dataSourceName . ,it)) work/sqls-connections))
`(((driver . "postgresql") (dataSourceName . ,(car work/sqls-connections)))))
;; TODO: Remove this 'car'!
(add-hook 'sql-mode-hook 'lsp)
(use-package org-modern)
(defun my/execute-query-at-point ()
"Execute query at point and make resulting table an Org table and modernise it"
(interactive)
(lsp-sql-execute-paragraph)
(other-window 1) (org-modern-global-mode) (org-mode) (read-only-mode -1)
(while (re-search-forward "^\+" nil t) (replace-match "|" nil t))
(toggle-truncate-lines)
(beginning-of-buffer) (execute-kbd-macro (read-kbd-macro ""))
(read-only-mode) (other-window -1)
(local-set-key "q" (lambda () "Quit buffer" (interactive) (ignore-errors (kill-buffer-and-window)))))
;; TODO: FIXME: Debugger entered--Lisp error: (void-variable sql-mode-map)
;; (bind-key "C-c C-c" #'my/execute-query-at-point 'sql-mode-map)
;; (bind-key "C-c C-" #'my/execute-query-at-point 'sql-mode-map)
(defun w-sql ()
"Quickly run a SQL query, then dispose of the buffer when done.
Uses the first connection available, to change connections
invoke M-x `lsp-sql-switch-connection'."
(interactive)
;; LSP only works on files; not buffers; so I use this file.
(find-file "~/.emacs.d/scratch.sql")
(insert work/sql-queries) ;; docs and examples
(sql-mode)
(hs-minor-mode -1) ;; I don't want the above comments to be collapsed away.
(beginning-of-buffer))
#+end_src
#+begin_details "Previous setup ~ ejc-sql [Disabled]"
- ❌ ~ejc-sql~ crashes with updates.
- ✔ I like that ejc-sql gives me M-. to jump to definitions of tables/functions/etc.
- “Go to definition”: [M-.] M-x ejc-describe-entity ⇒ Show source code for a stored view, function, table, etc.
- Get entity definition: show creation SQL of view, package, function, procedure or type.
- C-c e t ⇒ See list of tables
- ✔ ejc works with org-mode out of the box; https://github.com/kostafey/ejc-sql#use-with-org-mode
⇒ BEST OF BOTH WORLDS? ⇐
(setq ejc-sql-separator "-- /") ;; Otherwise LSP sql server sees ‘/’ as a syntax error.
#+begin_src emacs-lisp :tangle no
;; (system-packages-ensure "leiningen")
;; NOTE: You must commented out the (require 'ejc-direx) from ejc-sql.el
;; Reason: https://github.com/kostafey/ejc-sql/issues/163
(use-package ejc-sql
:config
(require 'ejc-company)
(push 'ejc-company-backend company-backends)
(setq ejc-completion-system 'standard) ;; Use my setup; i.e., Helm.
;; [C-u] C-c C-c ⇒ Evaluate current query [With JSON PP].
(bind-key "C-c C-c"
(lambda () (interactive)
(setq ejc-sql-complete-query-hook
(if current-prefix-arg
'(w-ejc-result-pp-json) ;; Defined below
'((lambda () ;; Give each line of text just one screen line.
(switch-to-buffer-other-window "*ejc-sql-output*")
(visual-line-mode -1)
(toggle-truncate-lines)
(other-window -1)))))
(ejc-eval-user-sql-at-point))
'sql-mode-map))
(defun w-sql ()
"Quickly run a SQL query, then dispose of the buffer when done.
By default uses a connection named “xxxx”, to see a list of
other connections call with a prefix argument."
(interactive)
;; Get DB credentials. One does “M-x ejc-connect-interactive” once, then
;; “M-x ejc-insert-connection-data” and paste that into your init; then
;; “M-x ejc-connect” provides a completion of possible DBs to connect to.
(load-file "~/Desktop/work.el")
;; For the following: Alternatively, we could make a new binding such as “C-c C-j”
;; which temporarily adds to this hook, then calls
(add-to-list 'ejc-sql-complete-query-hook 'w-ejc-result-pp-json) ;; Defined below
(require 'ejc-sql)
(-let [connection-name (if current-prefix-arg (ejc-read-connection-name) "xxxx")]
(switch-to-buffer-other-window (format "*SQL/%s*" connection-name))
(thread-last
`("\n\n/\n-- DOCS & EXAMPLES\n--"
"-- SQL queries should be seperated by “/”"
"-- [C-u] C-c C-c ⇒ Evaluate current query [With JSON PP]"
"-- In result window, TAB/RET to navigate the columns/rows."
"-- C-c e t ⇒ List all tables"
"-- C-h t ⇒ ‘H’elp for a ‘t’able"
"\nselect 1 + 2 as \"Numerical, yeah!\""
"\n/\n"
"-- More examples of useful SQL queries I might need, but don't want to remember"
;; I've moved them out to my private work.el file.
,@work/sql-queries)
(s-join "\n")
insert)
(sql-mode)
(hs-minor-mode -1) ;; I don't want the above comments to be collapsed away.
(ejc-connect connection-name)
(beginning-of-buffer)
(message "Connecting to DB... please wait a moment")))
(defun w-ejc-result-pp-json ()
"Pretty print JSON ejc-result buffer."
(interactive)
(ignore-errors
(switch-to-buffer-other-window "*ejc-sql-output*")
(beginning-of-buffer)
(re-search-forward "{")
(backward-char 1)
(delete-region (point-min) (point))
(end-of-buffer)
(re-search-backward "|")
(kill-line)
(json-mode)
(json-pretty-print-buffer)
(other-window -1)
(message-box "hiya")))
#+end_src
;; Add minimal table autocomplete to SQL
(require 'ejc-company)
(push 'ejc-company-backend company-backends)
(add-hook 'ejc-sql-minor-mode-hook
(lambda ()
(company-mode t)))
#+end_details
- *Postgres is the Emacs of Databases:* /It has extensions!/ E.g., It can be
extended to write stored functions in Ruby, Python, and [[https://plv8.github.io/#:~:text=for(var%20i%3D0%3B%20i%3Ckeys.length%3B%20i%2B%2B)%7B%0A%20%20%20%20%20%20%20%20o%5Bkeys%5Bi%5D%5D%20%3D%20vals%5Bi%5D%3B%0A%20%20%20%20%7D%0A%20%20%20%20return%20o%3B][in-particular
JavaScript]]. So neat!
- [[https://dzone.com/articles/why-postgresql-so-awesome][Why PostgreSQL is so Awesome - DZone Java]]
- [[https://www.2ndquadrant.com/en/blog/postgresql-is-the-worlds-best-database/][PostgreSQL is the worlds' best database - 2ndQuadrant | PostgreSQL]]
- [[https://www.craigkerstiens.com/2012/04/30/why-postgres/][Why Postgres - Craig Kerstiens]]
*** TODO Peer Review / Pull Request Template for Work
:PROPERTIES:
:CUSTOM_ID: Peer-Review-Pull-Request-Template-for-Work
:END:
I run TODO. doc.w-pr-template to get a new Org buffer with a review template. I make
notes and check-off boxes with ~C-c C-c~ as usual, and when I'm done I press ~C-c
C-s~ to copy the buffer to clipboard, in markdown format. Then I can paste it
into Github.
#+begin_src emacs-lisp
(cl-defun w-pr-template ()
"Hi"
(interactive)
(-let [buf "PR Template ~ Press “C-c C-s” when done"]
(ignore-errors (kill-buffer buf))
(switch-to-buffer buf)
(insert "w-pr-template")
(yankpad-expand)
(org-mode)
(beginning-of-buffer)
(use-local-map (copy-keymap org-mode-map))
(local-set-key (kbd "C-c C-s")
`(lambda ()
(interactive)
(beginning-of-buffer)
(replace-string "[X]" "✅")
(beginning-of-buffer)
(replace-string "[ ]" "❌")
(beginning-of-buffer)
(replace-string "[-]" "🚧")
(-let [org-export-with-toc nil]
(org-md-export-as-markdown)
(kill-ring-save (point-min) (point-max)))
(kill-buffer-and-window) ;; Kills the new org-md-export buffer
(kill-buffer ,buf) ;; Kills this temporary PR template buffer
(message "PR notes saved to clipboard in Github markdown")))))
#+end_src
#+begin_src org :tangle "~/.emacs.d/yankpad.org" :comments none
,** w-pr-template: Peer Review / Pull Request Template for Work
I followed the testing instructions and everything look's good 😁
Below is a detailed checklist of what I went through.
--------------------------------------------------------------------------------
1. [ ] Pull Request: The PR template was fully filled out.
- [ ] Clear description of the problem and how it was solved.
- [ ] I've cross-checked the description with the associated Jira ticket; and
everything is implemented.
- [ ] I've ticked-off the PR's check-boxes.
- [ ] Good use of bullet points (-) and code font (‵, ‷) to make the prose
easier to read.
- [ ] The commit messages are well-written.
- [ ] Travis CI succeeds.
- [ ] PR author annotated source code, with Github comments, before the review.
- Annotations guide the reviewer through the changes, showing which files to look at first and defending the reason behind each code modification.
2. [ ] Functionality: The code behaves as the author intended.
- [ ] I was able to reproduce the bug on ~main~.
- [ ] Ran the code and used it as an end-user would.
Namely, I made a new form, submitted an instance, checked ~In-Progress~,
& ~Form Reports~.
- [ ] I've tried all kinds of quotes and unicode, "𝒰"\‘ℕ’/𝒊′ℭ″𝑂؛𝒟⨾'∃',
input for text inputs; as well as special chars: +-_)(*&^%$#@!~`'".;>
- Remove some redundancy using a bit of laws of algorithmics, namely
+ ~[𝒆𝒕𝒂-𝒓𝒆𝒅𝒖𝒄𝒕𝒊𝒐𝒏] ⋯(x => f(x))⋯ ≡ ⋯f⋯~
+ ~[𝒊𝒇-𝒅𝒊𝒔𝒕𝒓𝒊𝒃𝒖𝒕𝒊𝒗𝒊𝒕𝒚] (a ? f(b) : f(c)) ≡ f(a ? b : c)~
which increase readability a tad.
# Especially when “f” is a lengthy expression; it may also be ideal to give
# “a ? b : c” a local name.
- Fail fast, validate arguments [we have some in-house validation util libraries]
- Be aware that ~0, "", []~ are all falsey values in JS: If a variable ~x~
can be one of those things, then ~if (x)~ is not always approriate; better
may be ~if(typeof x === 'integer')~ since this communicates two things (1)
the variable is defined, and (2) what it's type expected is.
+ Likewise, better use ~typeof~ instead of ~x !== null~.
- You have variables declared a bit from their use sites; the distance
creates an unnecessary disconnect ---especially since you don't use these
variables elsewhere. Please relocate them to be closer to their use sites.
- Strings are sanitised
- Errors are caught; with ~try/catch~
- Global variables are avoided, when possible.
- ~const~ is preferred to ~let~; ~var~ should seldom be used.
- Use ~var~ and ~function~ when you want definitions hoisted to the top of
their enclosing scope.
- ~===~ is preferred to ~==~.
- Use default arguments instead of short-circuiting or conditionals
- ~f (x) { x = x || defaultValue; ⋯ }~ ≡ ~f (x = defaultValue) { ⋯ }~.
- Named parameters can also be optional, with default values:
~f(obj) { let prop = obj.prop || defaultProp; ⋯}~ ≣ ~f ({prop =
defaultProp}) { ⋯ }~
- Unless you really need an array, handled an indefinite number of
arguments using rest parameters: ~function f(...args) {⋯ // use ‘args’ as
an array}~ can be invoked ~f(x₁, x₂, …)~ _without_ array brackets; or as
~f(...arr)~ if you have an array in-hand.
- Function arguments: 3 or fewer ideally
- If you need to declare an argument but are not using it, prefix it's name
with an underscore.
- Encapsulate conditionals in a separate _well-named_ function, if possible
- Avoid negative conditionals; e.g., by making use of well-choosen names.
- Use Demorgan's rules: ~!x && !y ≣ !(x || y)~ and ~!x || !y ≣ !(x && y)~.
- Use ~try/catch~ with ~async/await~; or promises with both ~then~ and ~catch~.
- Don't ignore rejected promises, log it to external logging service
- Related chunks of code are clearly demarcated.
- If an anonymous function is too long, more than 2 lines, give it a name:
E.g., in JS, ~arr.map(x => ...) ≣ arr.map( function
doingSomeComplexStuff(x) { return ...} )~. The name aids in communicating
the intent, and is useful for debugging.
- [ES6] Braces are used for block scope, and not simulated using IIFEs.
- Avoid explicit newlines with ~+ "\n" +~ in-favour of Template Literals, which preserve line
breaks.
- Use Destructuring instead of explicit projections; aids in readability.
- Note∶ ~let y = x.y~ ≡ ~let {y} = x~ only holds when ~x~ is not ~null~
(and so when ~x~ is not a expression involving ~?.~).
,#+html:
#+end_src
** COMMENT w-screencapture
:PROPERTIES:
:CUSTOM_ID: w-screencapture
:END:
#+begin_src emacs-lisp
(bind-key "C-c s"
(cl-defun w-screencapture ()
"Interactively capture screen and save to clipboard; then paste in Slack, etc, with ⌘-c.
After we run this command, we can swipe up on mousepad to select different desktops, then
click & drag to select portition of screen to capture.
Captured screen is NOT saved to disk, only copied to clipboard.
In MacOs,
+ Command + Shift + 5 ⇒ Select screen record
+ Command + Shift + 4 ⇒ Selection Screenshot
+ Command + Shift + 3 ⇒ Screenshot
See: https://osxdaily.com/2011/08/11/take-screen-shots-terminal-mac-os-x"
(interactive)
(async-shell-command "screencapture -i -c")))
(cl-defun w-delete-all-screenshots ()
"Delete all “Screen Shot ⋯” files in ~/Desktop."
(interactive)
(thread-last (shell-command-to-string "cd ~/Desktop; ls")
(s-split "\n")
(--filter (s-starts-with-p "Screen Shot" it))
(--map (f-delete (format "~/Desktop/%s" it)))))
#+end_src
*** TODO Screencapturing the Current Emacs Frame
:PROPERTIES:
:CUSTOM_ID: Screencapturing-the-Current-Emacs-Frame
:END:
Sometimes an image can be tremendously convincing, or at least sufficiently
inviting. The following incantation is written for MacOS and uses it's native
=screencapture= utility, as well as =magick=.
#+BEGIN_SRC emacs-lisp
(defun my/capture-emacs-frame (&optional prefix output)
"Insert a link to a screenshot of the current Emacs frame.
Unless the name of the OUTPUT file is provided, read it from the
user. If PREFIX is provided, let the user select a portion of the screen."
(interactive "p")
(defvar my/emacs-window-id
(s-collapse-whitespace (shell-command-to-string "osascript -e 'tell app \"Emacs\" to id of window 1'"))
"The window ID of the current Emacs frame.
Takes a second to compute, whence a defvar.")
(let* ((screen (if prefix "-i" (concat "-l" my/emacs-window-id)))
(temp (format "emacs_temp_%s.png" (random)))
(default (format-time-string "emacs-%m-%d-%Y-%H:%M:%S.png")))
;; Get output file name
(unless output
(setq output (read-string (format "Emacs screenshot filename (%s): " default)))
(when (s-blank-p output) (setq output default)))
;; Clear minibuffer before capturing screen or prompt user
(message (if prefix "Please select region for capture …" "♥‿♥"))
;; Capture current screen and resize
(thread-first
(format "screencapture -T 2 %s %s" screen temp)
(concat "; magick convert -resize 60% " temp " " output)
(shell-command))
(f-delete temp)
;; Insert a link to the image and reload inline images.
(insert (concat "[[file:" output "]]")))
(org-display-inline-images nil t))
(bind-key* "C-c M-s" #'my/capture-emacs-frame)
#+END_SRC
Why this way? On MacOS, ImageMagick's =import= doesn't seem to work ---not at all
for me! Also, I dislike how large the resulting image is. As such, I'm using
MacOS's =screencapture= utility, which in-turn requires me to somehow obtain frame
IDs. Hence, the amount of work needed to make this happen on my system was most
simple if I just wrote it out myself rather than tweaking an existing system.
+ ~C-c C-x C-v~ ⇒ Toggle inline images!
** Tree cmd, also treemacs for navigating a new repository :RelocateToDiredSection:
(system-packages-ensure "tree")
- A useful way to get an overview of a new repository.
- Alternatively, a nice way to quickly see what's at the current level and all subdirectories.
- =tree | ls=
I might browse around the various subdirectories trying to get a feel for the
layout of the project. I might try lots of ls commands, or perhaps something
like
tree | less
#(or perhaps)#
and then within less I can use the interactive search function / to look around for keywords.
E.g., =tree | less= then =/ karate= will show me a tree overview with all files that
have the word “karate” in their full filename; then =/ png= will do a new search
(on the tree overview) to show me all files with the phrase =png= (including as an
extension).
Of-course, to actually do anything with the files (like mass renaming), there's
Emacs' Dired (the directory editor).
#+begin_src emacs-lisp
(defun my/explore-directory ()
"Run “tree | less” for `default-directory'."
(interactive)
(vterm-toggle)
(vterm-send-string "tree|less")
(vterm-send-return)
(message "Press “/ 𝒳” to narrow to files with 𝒳 in their path."))
#+end_src
** Jump between windows using Cmd+Arrow & between recent buffers with Meta-Tab :Relocate:
:PROPERTIES:
:CUSTOM_ID: Jump-between-windows-using-Cmd-Arrow-between-recent-buffers-with-Meta-Tab
:END:
We can use ~C-x o~ to switch to the ‘o’ther window, and ~C-u 𝓃 C-x o~ to switch to
the 𝓃-th next clockwise window, but using ~s-↑,↓,←,→~ may be faster.
#+BEGIN_SRC emacs-lisp
(use-package windmove
:config ;; use command key on Mac
(windmove-default-keybindings 'super)
;; wrap around at edges
(setq windmove-wrap-around t))
#+END_SRC
*** [C-u]-M-TAB to move between buffers
:PROPERTIES:
:CREATED: [2025-09-05 Fri 22:11]
:END:
The [[https://github.com/killdash9/buffer-flip.el][docs]], for the following, have usage examples.
#+BEGIN_SRC emacs-lisp
(use-package buffer-flip
:bind
(:map buffer-flip-map
("M-"
(or color "pink"))
"
" "Details ﴾This is disabled, I'm not actively using it.﴿" "
") ;; Something to consider: (org-set-property "UNNUMBERED" "nil") (org-next-visible-heading 1) (insert "#+html:8. Press ⌘-e to edit this HTML block, in Web-mode
") ;; ;; ;; 9. Press C-u ⌘-e to guess the language of the next string (Rust); then ⌘-r C-c C-r to quickly run the code. ;; "fn main() { println!(\"{}\", \"hello!\"); }" ;; ;; ;; 10. Select & press “C-u ⌘-e” on the following, to edit it in whatever mode you want. ;; ;; select * from table -- Or just press ⌘-e and have the mode detected. ;; ;; ``` ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; ;; Setup to make the above ⌘-e behaviour happen. ;; Make "⌘-e" toggle editing string literals / select region / [Org/markdown] code block / comment block when programming. (when (fboundp '--map) (--map (bind-key "s-e" #'separedit it) '(prog-mode-map minibuffer-local-map help-mode-map))) ;; TODO: helpful-mode-map #+end_src #+begin_src emacs-lisp ;; TODO:Merge these changes upstream ;; I'm focusing on a specific region to edit, so let's not be distracted by anything else. ;; This makes the “editing stack” feel like a stack, with ⌘-e pushing new editing session buffers, ;; and C-c C-c, or ⌘-e on non-editable lines, to pop-off the stack. ;; (advice-add #'separedit :after (lambda (&rest _) (delete-other-windows))) ;; ;; NOTE: This actually breaks the stack nature of popping with ⌘-e; we need to actually save the stack via some list of buffers than push/pop buffers on that variable. ;; I don't want to be bothered for what mode I'm in, when a region is selected using current major mode. ;; I'll use a prefix, “C-u ⌘-e”, if I want to select a mode for my current selected text. (advice-add #'separedit--select-mode :before-until (lambda (&rest _) (when (and (not current-prefix-arg) (region-active-p)) (pp-to-string major-mode)))) ;; Also: When on a string ∷ (advice-add #'separedit--select-mode :before-until (lambda (&rest _) "When on a string ∷ + ⌘-e ⇒ Edit string at point + C-u ⌘-e ⇒ Auto-detect my string's major mode + C-u C-u ⌘-e ⇒ Let me select a major mode" (-let [str? (ignore-errors (thing-at-point 'string))] (case (car current-prefix-arg) (4 (when str? (pp-to-string (my/detect-prog-mode str?)))) (_ nil))))) ;; NOTE: By default, separedit provides colouring for 'strings', "strings", and `strings' ;; This doesn't look very good when I have a single quote within double quotes: ;; In an Emacs Lisp buffer, editing the string "Bob's Work" gives unexpected highlighting. ;; ``` ;; (advice-add #'separedit :after ;; (lambda (&rest _) ;; (when (s-ends-with? "string-mode" (pp-to-string major-mode)) ;; (text-mode)))) ;; ``` #+end_src #+begin_src emacs-lisp ;; In the indirect buffer, make ⌘-e finish editing. (use-package edit-indirect :config (bind-key "s-e" (lambda () (interactive) (or (ignore-errors (call-interactively #'separedit)) (call-interactively #'edit-indirect-commit))) #'edit-indirect-mode-map)) ;; I also have “s-e” bound to `org-edit-src-exit'. (advice-add 'org-edit-src-exit :before-until (lambda (&rest r) (when (ignore-errors (separedit)) t))) #+end_src #+begin_src emacs-lisp ;; → ⌘-e on an Org paragraph pops-up an edit session in Org mode. ;; → ⌘-e on a selection in Org mode pops-up an edit session in Org mode. ;; TODO: Consider forming an alist for special blocks to refer to their preferred ;; edit mode, defaulting to Org-mode? Perhaps something to consider /after/ ;; addressing the bug below. ;; (advice-unadvice 'org-edit-special) MA: TODO: FIXME: Delete this? (advice-add 'org-edit-special :around (lambda (orginal-function &rest r) (cond ((region-active-p) (call-interactively #'edit-indirect-region) (org-mode)) ((equal 'paragraph (car (org-element-at-point))) (mark-paragraph) (call-interactively #'edit-indirect-region) (org-mode)) (t (or (ignore-errors (apply orginal-function r)) ;; We try to edit a special block when orginal-function fails. ;; This way src blocks are not confused with the more generic idea of special blocks. (when (my/org-in-any-block-p) ;; Note using org-element-at-point doesn't work well with special blocks when you're somewhere within the block. ;; It only works correctly when you're on the boundary of the special block; which is not ideal. ;; This is why I'm not using: (org-element-property :begin elem). (-let [(start . end) (my/org-in-any-block-p)] (set-mark-command start) (goto-char end) (previous-line 2) (end-of-line) ;; FIXME: Still shows #+end_XXX for some reason. (call-interactively #'edit-indirect-region) (org-mode)))))))) #+end_src #+begin_src emacs-lisp ;; where... (defun my/org-in-any-block-p () "Return non-nil if the point is in any Org block. The Org block can be *any*: src, example, verse, etc., even any Org Special block. This function is heavily adapted from `org-between-regexps-p'. Src: https://scripter.co/splitting-an-org-block-into-two/" (save-match-data (let ((pos (point)) (case-fold-search t) (block-begin-re "^[[:blank:]]*#\\+begin_\\(?1:.+?\\)\\(?: .*\\)*$") (limit-up (save-excursion (outline-previous-heading))) (limit-down (save-excursion (outline-next-heading))) beg end) (save-excursion ;; Point is on a block when on BLOCK-BEGIN-RE or if ;; BLOCK-BEGIN-RE can be found before it... (and (or (org-in-regexp block-begin-re) (re-search-backward block-begin-re limit-up :noerror)) (setq beg (match-beginning 0)) ;; ... and BLOCK-END-RE after it... (let ((block-end-re (concat "^[[:blank:]]*#\\+end_" (match-string-no-properties 1) "\\( .*\\)*$"))) (goto-char (match-end 0)) (re-search-forward block-end-re limit-down :noerror)) (> (setq end (match-end 0)) pos) ;; ... without another BLOCK-BEGIN-RE in-between. (goto-char (match-beginning 0)) (not (re-search-backward block-begin-re (1+ beg) :noerror)) ;; Return value. (cons beg end)))))) #+end_src I'd like to [[https://github.com/andreasjansson/language-detection.el][guess the language]] I'm in, when working with strings. #+begin_src emacs-lisp (use-package language-detection) ;; Usage: M-x language-detection-buffer ⇒ Get programming language of current buffer ;; Also, (language-detection-string "select * from t") ;; ⇒ sql ;; TODO: Push this upstream; https://github.com/andreasjansson/language-detection.el/issues/1 (cl-defun my/detect-prog-mode (&optional string) "Guess programming mode of the current buffer, or STRING if it is provided. When called interactively, it enables the mode; from Lisp it just returns the name of the associated mode. ;; Example Lisp usage (call-interactively #'my/detect-prog-mode) `language-detection-buffer' returns a string which is not always the name of the associated major mode; that's what we aim to do here." (interactive) (defvar my/detect-prog-mode/special-names '((c . c-mode) (cpp . c++-mode) (emacslisp . emacs-lisp-mode) (html . web-mode) ;; I intentionally want to use this alternative. (matlab . octave-mode) (shell . shell-script-mode) (visualbasic . visual-basic-mode) (xml . sgml-mode)) "Names in this alist map a language to its mode; all other languages 𝒳 have mode ‘𝒳-mode’ afaik.") (let* ((lang (if string (language-detection-string string) (language-detection-buffer))) (mode (or (cdr (assoc lang my/detect-prog-mode/special-names)) (intern (format "%s-mode" lang))))) (if (called-interactively-p 'any) (progn (call-interactively mode) (message "%s enabled!" mode)) mode))) #+end_src + ⌘-e to edit an Org table cell; see [[https://orgmode.org/manual/Built_002din-Table-Editor.html][here]] for built-in table editing commands. #+begin_src emacs-lisp (advice-add #'org-edit-special :before-until (lambda (&rest r) (when (equal 'table-row (car (org-element-at-point))) (call-interactively #'org-table-edit-field)))) #+end_src ** ⌘-r, ⌘-i, ⌘-o: Sleek Semantic Selection :PROPERTIES: :CUSTOM_ID: Sleek-Semantic-Selection :END: Super sleek way to select regions: Anywhere press kbd:⌘-r to select the current word, press it again to select sentence, then again for the current paragraph, then more to get the current section. #+begin_src emacs-lisp (use-package expand-region :bind ("s-r" . #'er/expand-region)) #+end_src You can watch an introductory ~3 minute video to expand-region at [[http://emacsrocks.com/e09.html][Emacs Rocks!]]. That is, /repeated ⌘+r expands the selection to the next logical segment of text:/ In writing this means “Word, sentence, paragraph”, and in programming this means “identifier, then incrementally larger scopes”. *** Semantic Change :Disabled: :PROPERTIES: :CUSTOM_ID: Semantic-Change :END: Using kbd:⌘-i and kbd:⌘-o we can quickly, for example, delete a string or its contents; or delete a {}-block or just its contents; or delete a ()-argument list or just its contents, etc. ~change-inner~ gives you vim's ~ci~ command: - ~change-inner {~ ⇒ Delete all text starting from the first ‘{’ delimiter to the next one; but /keep the delimiters/. - ~change-outer {~ ⇒ As above, but also delete the delimiters. #+begin_src emacs-lisp :tangle no (use-package change-inner :bind (("s-i" . #'change-inner) ("s-o" . #'change-outer))) #+end_src ** Documentation *** Editor Documentation with Contextual Information :PROPERTIES: :CUSTOM_ID: Editor-Documentation-with-Contextual-Information :END: /Emacs is an extensible self-documenting editor!/ Let's use a helpful Emacs /documentation/ system that cleanly shows a lot of contextual information ---then let's /extend/ that to work as we want it to: ~C-h o~ to describe the symbol at point. #+begin_src emacs-lisp (use-package helpful :commands (helpful-callable helpful-symbol) :bind (("C-h k" . #'helpful-key) ("C-h o" . #'my/describe-symbol))) (defun my/describe-symbol (symbol) "A “C-h o” replacement using “helpful”. If there's a thing at point, offer that as default search item. If a prefix is provided, i.e., “C-u C-h o” then the built-in “describe-symbol” command is used. ⇨ Pretty docstrings, with links and highlighting. ⇨ Source code of symbol. ⇨ Callers of function symbol. ⇨ Key bindings for function symbol. ⇨ Aliases. ⇨ Options to enable tracing, dissable, and forget/unbind the symbol!" (interactive "P") (let* ((sym-at-pt (symbol-at-point)) (default (and (symbolp sym-at-pt) (symbol-name sym-at-pt))) (prompt (if default (format "Describe symbol (default %s): " default) "Describe symbol: ")) (pred (lambda (sym) ; SYM is a symbol when COLLECTION is an obarray (cl-some (lambda (x) (funcall (cadr x) sym)) describe-symbol-backends))) (name (completing-read prompt obarray ; ← use obarray directly pred t ; require-match nil nil default)) ; ← default goes here (sym (intern name))) (if current-prefix-arg (describe-symbol sym) ; C-u C-h o → built-in (if (or (functionp sym) (macrop sym) (commandp sym)) (helpful-callable sym) (helpful-symbol sym))))) #+END_SRC I like [[https://github.com/Wilfred/helpful][helpful]] and wanted it to have the same behaviour as ~C-h o~, which ~helpful-at-point~ does not achieve. The incantation above makes ~C-h o~ use ~helpful~ in that if the cursor is on a symbol, then it is offered to the user as a default search item for help, otherwise a plain search box for help appears. Using a universal argument lets us drop to the built-in help command. *** [[https://github.com/xuchunyang/elisp-demos][Append existing ELisp docstrings with example use and actual output.]] :PROPERTIES: :CUSTOM_ID: Let's-make-working-with-Emacs-Lisp-even-better :END: If you query ~C-h o mapcar~ you get some nice docs, but it'd be even nice to get some example usage of that method. #+begin_src emacs-lisp (use-package elisp-demos :config ;; Show demos when I do a `C-h o'. (advice-add 'helpful-update :after #'elisp-demos-advice-helpful-update) ;; Show demos in tooltips when I pause to select a completion, in Emacs Lisp mode. (advice-add 'describe-function-1 :after #'elisp-demos-advice-describe-function-1)) #+end_src *** Get CheatSheets and view them easily :Disabled: :PROPERTIES: :CUSTOM_ID: Get-CheatSheets-and-view-them-easily :header-args: :tangle no :END: #+begin_src emacs-lisp (defvar my/cheatsheet/cached-topics nil) (cl-defun my/cheatsheet (&optional topic) "Clone Al-hassy's ⟨TOPIC⟩CheatSheet repository when called from Lisp; visit the pretty HTML page when called interactively. - Example usage: (my/cheatsheet \"Vue\") - Example usage: M-x my/cheatsheet RET Vue RET." (interactive) (if (not topic) (browse-url (format "https://alhassy.github.io/%sCheatSheet" (completing-read "Topic: " my/cheatsheet/cached-topics))) (push topic my/cheatsheet/cached-topics) (maybe-clone (format "https://github.com/alhassy/%sCheatSheet" topic)))) #+end_src Let's actually get some repos locally, and use: ~M-x my/cheatsheet~ to view the pretty HTML (or PDF) sheets. #+begin_src emacs-lisp (mapcar #'my/cheatsheet '("ELisp" "GojuRyu" "Rust")) ; Python Prolog Vue Agda JavaScript ; Clojure Ruby Oz Coq Cats Haskell FSharp OCaml #+end_src *** How do I do something? :Disabled: :PROPERTIES: :CUSTOM_ID: How-do-I-do-something :header-args: :tangle no :END: When programming, sometimes you just gotta Google “how do I do ⋯”. - The usual process is (1) open a browser, (2) make a Google query, (3) look at StackOverflow's most upvoted answer for your query, (4) copy-paste the code solution/example to your editor; [(5) get distracted by interesting things you'd like to read]. - Better would be to use the [[https://github.com/gleitz/howdoi][howdoi]] tool, which gives instant coding answers for common questions via the command line. - Below, my /Emacs Lisp/ function doc : howdoi let's me reduce the 4-step process to just 2 steps: Write your query /anywhere/ then call ~M-x howdoi~ on it to replace the query with the answer. (Or ~C-u M-x howdoi~ to see the full answer and a link to it on StackOverflow.) | /⚡ Never open your browser to look for help again ⚡/ | #+begin_src emacs-lisp (system-packages-ensure "howdoi") (cl-defun howdoi (&optional show-full-answer) "Instantly insert coding answers. Replace a query with a code solution; replace it with an entire answer if a prefix is provided. Example usage: On a new line, write a question such as: search and replace buffer Emacs Lisp Then invoke ‘M-x howdoi’ anywhere on the line to get a code snippet; or ‘C-u M-x howdoi’ to get a full answer to your query. " (interactive "P") (let ((query (s-collapse-whitespace (substring-no-properties (thing-at-point 'line)))) (flag (if show-full-answer "-a" ""))) (beginning-of-line) (kill-line) (insert (shell-command-to-string (format "howdoi %s %s" query flag))))) #+end_src *** Elisp live documentation in the mini-buffer :PROPERTIES: :CUSTOM_ID: Eldoc-for-Lisp-and-Haskell :END: In =emacs-lisp-mode= we can enable =eldoc-mode= ---“Elisp Live Documentation”--- to display information about a function or a variable in the echo area. #+BEGIN_SRC emacs-lisp (use-package eldoc :hook (emacs-lisp-mode . turn-on-eldoc-mode)) ;; Slightly shorten eldoc display delay. (setq eldoc-idle-delay 0.4) ;; Default 0.5 #+END_SRC ** Jumping to definitions & references :PROPERTIES: :CUSTOM_ID: Jumping-to-definitions-references :END: Friendly reminder that ~M-.~ takes you to the definition, and ~M-,~ takes you back to where you originally where. Out-of-the-box Emacs has ‘xref’ utilities ~M-.~ and ~C-u M-.~ to [[https://www.gnu.org/software/emacs/manual/html_node/emacs/Xref.html#Xref][Find Identifier References]]; however, tags to source definitions need to be generated using the =etags= program. Nonetheless, the xref utilites are impressive and some just work: For example, ~M-?~ cleverly finds /all/ references for an identifier in ‘near by’ files; whereas ~C-u M-. RET my/.*~, for example, uses the given regular expression to list all identifiers with prefix ~my/~, thereby listing my personally defined names ^_^ | =C-M-. 𝓇𝓮ℊ𝓮𝓍= | Find all identifiers whose name matches the given pattern | Let's get [[https://github.com/jacktasia/dumb-jump][dumb-jump]], where the ‘dumb’ is possibly due to the fact that it works by brute-force regular-expression lookup of pre-defined ‘definitional template’ rules. It “just works” ^_^ #+BEGIN_SRC emacs-lisp (use-package dumb-jump :bind (("M-g q" . dumb-jump-quick-look) ;; Show me in a tooltip. ("M-g ." . dumb-jump-go-other-window) ("M-g b" . dumb-jump-back) ("M-g p" . dumb-jump-go-prompt) ("M-g a" . xref-find-apropos)) ;; aka C-M-. :config ;; If source file is visible, just shift focus to it. (setq dumb-jump-use-visible-window t)) #+END_SRC In Lisp, for binding macros, it lists all possible mentions of the bound variable ---the first is likely what is desired. Alternatively, one could just add the necessary rule to the variable =dumb-jump-find-rules=. Otherwise, it works fine even for locally bound definitions. It works depending on the extension of a file. *** An “auto read only” detection mechanism ---when jumping to definitions :Disabled: :PROPERTIES: :CUSTOM_ID: An-auto-read-only-detection-mechanism-when-jumping-to-definitions :header-args: :tangle no :END: Files in 3ʳᵈ-party directories should be read-only whenever I open them, when I'm jumping to definitions (with ~M-.~). #+begin_src emacs-lisp ;; Usage: Press “M-”. “use-package” below and you can accidentally alter the source code! ;; But in this case you likely just wanted to see the 3ʳᵈ-party definition, not alter it. ;; As such, with this advice, the source will not be alterable (unless you toggle read-only mode). (advice-add #'xref-find-definitions :after (lambda (&rest _) (when (--map (s-ends-with? it (f-parent buffer-file-name)) '("lisp/emacs-lisp" "/lisp" ".emacs.d/elpa/")) (read-only-mode)))) #+end_src ** Comments *** Commenting :PROPERTIES: :CUSTOM_ID: Commenting :END: Let's get some nifty [[https://github.com/remyferre/comment-dwim-2][commenting]] features ---the link has nice usage gifs. + [[kbd:][M-;]] repeatedly does (1) comments current line, (2) inserts a comment at the end of the current line, and (3) deletes an existing end-of-line comment. [[kbd:][C-u_M-;]] indents the current enf-of-line comment with any above it. For use with Org-mode, it's best to use doc:org-edit-src-code ---which I've bound to [[kbd:][⌘ e]]. #+begin_src emacs-lisp (use-package comment-dwim-2 :bind ("M-;" . comment-dwim-2)) ;; Not ideal: M-; comments a parent Org heading and not the current line. ;; (define-key org-mode-map (kbd "M-;") 'org-comment-dwim-2) #+end_src *** Emphasised Comments: Useful for warnings :PROPERTIES: :CUSTOM_ID: Emphasised-Comments :END: #+begin_src emacs-lisp ;; In VSCode, with the “Better Comments” extension, comments starting with a “bang” are made to stand out, via bold red. ;; Let's do the same thing in Emacs. ;; I did not look around, there might be a package/option for this 🤷 (add-hook 'prog-mode-hook (defun emphasize-comments-starting-with-! () (highlight-lines-matching-regexp ".*\\*.*!.*" 'hi-red-b) (highlight-lines-matching-regexp ".*//!.*" 'hi-red-b) (highlight-lines-matching-regexp ";;!.*" 'hi-red-b))) ;;! Look it works (｡◕‿◕｡) #+end_src *** Comment-boxes up to the fill-column ---or banner instead? :PROPERTIES: :CUSTOM_ID: Comment-boxes-up-to-the-fill-column :END: GIF: https://endlessparentheses.com/images/comment-box.gif #+begin_src emacs-lisp (defun my/comment-box (b e) "Draw a box comment around the region but arrange for the region to extend to at least the fill column. Place the point after the comment box. Source: http://irreal.org/blog/?p=374 To do fancy stuff like removing boxes, centering them, etc see https://github.com/lewang/rebox2/blob/master/rebox2.el" (interactive "r") (let ((e (copy-marker e t))) (goto-char b) (end-of-line) (insert-char ? (- fill-column (current-column))) (comment-box b e 1) (goto-char e) (set-marker e nil))) #+end_src A comment box sometimes increases the size of a file more than I'd like, or more than others on my dev team would like. As such, let's try [[https://github.com/WJCFerguson/banner-comment][banner comments]]: - GIF: https://github.com/WJCFerguson/banner-comment/blob/35d3315683d3f97605207691b77e9f447af18fe2/demo.png #+begin_src emacs-lisp (use-package banner-comment) #+end_src Pretty slick! ** Text Folding ---Selectively displaying portions of a program :PROPERTIES: :CUSTOM_ID: Text-Folding :END: ⟦‼ TODO: hideshowvis shows ="*hideshowvis*"= literally in src code blocks upon export; as such we need to hook to exports so as to temporarily disable it. ⟧ #+begin_src emacs-lisp (require 'cl-lib) (defun my/disable-hs-hide-all (orig-fun &rest args) "Advise `org-export-dispatch` to disable `hs-hide-all` temporarily." ;; Without this, export hangs “Hiding all blocks...” (cl-letf (((symbol-function 'hs-hide-all) (lambda (&rest _) nil))) ;; Without this, export shows “*hideshowvis*” markers in my exported code blocks. (cl-letf (((symbol-function 'hideshowvis-highlight-hs-regions-in-fringe) (lambda (&rest _) nil))) (apply orig-fun args)))) (advice-add 'org-export-dispatch :around #'my/disable-hs-hide-all) #+end_src Literate programming within Org-mode is not always ideal or possible, so we use a programming mode directly and then may want to have arbitrary ‘sections’ of text folded up. Let's describe how to accomplish this goal. I've tried the feature-full folding modes [[https://github.com/gregsexton/origami.el][Origami-mode]] and ~yafolding-mode~, but it seems the /built-in/ TODO. doc.hs-minor-mode is the best: (0) It folds comments, (1) it's the fastest, and (2) it Just Worksᵀᴹ out-of-the-box. Coupled with Vimish folding, for arbitrary region folding; and a helpful hydra, I'm rather happy with my setup. On two JavaScript files, I found the following timings (using TODO. doc.elp-instrument-function and TODO. doc.elp-results): | Folding function | ~500 lines | ~2300 lines | |-------------------------+------------+-------------| | hs-hide-all | 0.00277 | 0.004358 | | origami-close-all-nodes | 0.00304 | 0.025569 | | yafolding-hide-all | 7.051795 | 74.252598 | (TODO: Maybe these timings are due to my config, I should try to reproduce these with ~emacs -Q~.) #+begin_box "There's a built-in, less featureful, alternative based on indentation!" Quickly fold-away code with TODO. doc.set-selective-display; e.g.,Number Guessing Game
{{reply(guess)}}
Number Guessing Game
{{reply(guess)}}
Hello, world
const element = document.getElementById(id); element.appendChild(tag); }") #+end_src A snippet for a form with (1) automatic alignment, and (2) submission handled by local JavaScript. #+begin_src emacs-lisp (my/add-emmet-snippet "form" "Automatically aligned form items
") #+end_src *** LSP for HTML + CSS :PROPERTIES: :CUSTOM_ID: LSP-for-HTML-CSS :END: Notes: I've tried [[https://emacs-lsp.github.io/lsp-mode/page/lsp-html/][LSP for HTML]] but I didn't find it provided much, and even worse, it seemed to ignore the useful information I get from Flycheck! + When I accidentally duplicate Ids, or miss important tag attributes, Flycheck ~(C-c !)~ reminds of these things! :-) + This is also [[https://emacs-lsp.github.io/lsp-mode/page/lsp-emmet/][LSP for Emmet]], which let's you expand any text you write as if it were an emmet snippet /such that/ you can ~TAB~ to the various editable regions in the expansion to fill them out. E.g., ~ul>li*5 RET~ produces a yas-snippet which you TAB through to fill out. - If you don't want some text to be treated as a snippet, press ~C-g~. - As above, this ruins flycheck support and highlighting ---requiring ~web-mode~ to get some highlighting. However, [[https://emacs-lsp.github.io/lsp-mode/page/lsp-css/][LSP for CSS]] is indispensable! + It provides auto-completion for properties, and if you pause then a tool tip with useful explanations of properties. :fire: + Moreover, if you press ~ENTER~ on a completion candidate, then you get to select a possible value from another list! + When I mouse hover over a property, I get a 1-line tooltip describing the property. + /No need to remember which properties are possible, what they do, and their possible values!/ Just start typing and see what pops-up! #+begin_src emacs-lisp :tangle no M-x lsp-install-server RET css-ls #+end_src #+begin_src emacs-lisp ;; When I accidentally duplicate a property in a rule, please report that as an error. (setq lsp-css-lint-duplicate-properties "error") ;; If I accidentally enter an unknown property (e.g., writing Canadian “colour” instead of American “color”), ;; then I'll be notified with an error notice. (setq lsp-css-lint-unknown-properties "error") (use-package lsp-mode :hook ;; Every programming mode should enter & start LSP, with which-key support (css-mode . lsp-mode) ;; Enter LSP mode (css-mode . lsp)) ;; Start LSP server #+end_src **** CSS Property Argument Information in the Echo Area :PROPERTIES: :CUSTOM_ID: CSS-Property-Argument-Information-in-the-Echo-Area :END: LSP for CSS shows me a tooltip with a description and the argument syntax of a property; but that's only when entering a new property. What if I'm updating a property; or just browsing a property and want some information on the arguments list? [[https://github.com/zenozeng/css-eldoc][css-eldoc]] to the rescue. - Eldoc-mode is a minor-mode which shows you, in the echo area, the argument list of the function call you are currently writing. #+begin_src emacs-lisp ;; [USAGE] In a CSS file, place cursor anywhere after the colon (but before ‘;’) ;; in “columns: 0ch;” or in “columns: ” and look at the echo area for how ;; arguments to this property should look like. (use-package css-eldoc :init (progn (require 'css-eldoc) (turn-on-css-eldoc))) #+end_src #+begin_src emacs-lisp :tangle no ;; [Possibly useful snippet to keep around.] ;; Change priority of a server; useful when multiple servers are running for a buffer. ;; (setf (lsp--client-priority (gethash 'emmet-ls lsp-clients)) 4) #+end_src *** Show me HTML+CSS Changes /Live as I Type/! :PROPERTIES: :CUSTOM_ID: Show-me-HTML-CSS-Changes-Live-as-I-Type :END: #+begin_src emacs-lisp (use-package impatient-mode) (use-package web-mode :init (add-to-list 'auto-mode-alist '("\\.html?\\'" . web-mode))) ;; C-c C-v: Browse buffer within external browser. ;; C-u C-c C-v: Ensure impatient-mode is enabled for current buffer and browse it WITHIN Emacs. ;; [xwidget-webkit has some bugs; e.g., sometimes buttons that should redirect don't do anything.] ;; [The “C-u” option is useful when I want to “see” the resulting HTML change as I type; e.g., new content or styling.] ;; [Note the “angular” snippet above works beautifully /within/ Emacs; use “b/f” to move backward/forward in the browser.] (bind-key "C-c C-v" (lambda (open-within-emacs) (interactive "P") (if (not open-within-emacs) (browse-url-of-buffer (current-buffer)) (unless (process-status "httpd") (httpd-start)) (unless impatient-mode (impatient-mode)) (let ((browser (car (--filter (s-starts-with? "*xwidget" (buffer-name it)) (buffer-list)))) (file (buffer-name))) (when browser (switch-to-buffer browser) (let (kill-buffer-query-functions) (kill-buffer))) (split-window-below) (other-window -1) (xwidget-webkit-browse-url (concat "http://localhost:8080/imp/live/" file)) (preview-it-mode -1) ;; Looks poor; and I don't need it when writing HTML. (other-window -1)))) 'web-mode-map) #+end_src #+begin_src emacs-lisp (bind-key "M-q" #'sgml-pretty-print 'web-mode-map) #+end_src *** VueJS :PROPERTIES: :CUSTOM_ID: VueJS :END: #+begin_src emacs-lisp (use-package vue-mode) #+end_src *** JSON :PROPERTIES: :CUSTOM_ID: JSON :END: Since web apps tend to be RESTful, payloads are [[https://www.json.org/json-en.html][JSON]]. To use the JSON, we need to tediously find paths to particular fields; let's do so with /automatically, without error./. When we open a JSON file, we are promoted to install an LSP server, which - Checks that the file is valid JSON. - Shows the full path to the cursor's location, at the top of the window. #+begin_src emacs-lisp (use-package json-mode) #+end_src Useful bindings are in the docstring of TODO. doc.json-mode. + kbd:C-c_C-f :: Pretty print buffer + kbd:C-c_C-p :: Copy path to field at point Note that there is also TODO. doc.json-pretty-print-buffer; which can be used to uglify a JSON buffer if a prefix is provided. Let's make a hydra for JSON, #+begin_src emacs-lisp (my/defhydra nil "JSON Browser" gamepad :Buffer ("p" #'json-mode-show-path "Copy path to field at point") ;; ("f" #'json-mode-beautify "Format Buffer") ;; ("m" (lambda () (interactive) (json-pretty-print-buffer t)) "Minify/ugligy buffer") ("t" (lambda () (interactive) (if my/json-hydra/pretty-printed? (json-pretty-print-buffer t) (json-mode-beautify (point-min) (point-max))) (setq my/json-hydra/pretty-printed? (not my/json-hydra/pretty-printed?))) "Toggle format/uglify of buffer" :toggle (progn (defvar my/json-hydra/pretty-printed? nil) my/json-hydra/pretty-printed?))) ;; TODO: (bind-key "C-c SPC" 'my/hydra/JSON\ Browser/body 'json-mode-map) ;; NOTE: “C-x SPC” is for rectangle editing. #+end_src Interesting, but not for me: [[https://github.com/taku0/json-par/][json-par: Emacs minor mode for structural editing of JSON]]. Also: [[https://transform.tools/json-to-jsdoc][JSON to X]] is a website to convert JSON to other formats, such as in Rust or as JSDoc type annotations. *** Turbolog: What's the value of this expression? :JavaScript: :PROPERTIES: :CUSTOM_ID: Turbolog-What's-the-value-of-this-expression :END: With [[https://github.com/Artawower/turbo-log][turbo-log]], I can select an expression then press [[kbd:C-x l l]] to have that expression be part of a console log message, in the next line, that also mentions the line number and buffer's name. I can toggle all these inserted messages to be comments with kbd:C-x_l_c and kbd:C-x_l_u, and when I'm done debugging I can quickly get rid of all of them with kbd:C-x_l_d. ( Before TurboLog, I used a snippet bound to kbd:l_l that inserted #+begin_src js :tangle no console.log("%c ******* LOOK HERE *******", "color: green; font-weight: bold;"); console.log({ List the variables here whose values you want to log }); #+end_src ) **** COMMENT TODO: Move some of the stuff below to the TurboLog Github repo. :Does_not_export_to_HTML: :PROPERTIES: :CUSTOM_ID: COMMENT-TODO-Move-some-of-the-stuff-below-to-the-TurboLog-Github-repo :END: #+begin_src emacs-lisp (unless noninteractive (setq turbo-log--prefix "%c ******* LOOK HERE *******") (defun length> (x y) (> (length x) y)) (defun length= (x y) (= (length x) y)) (ignore-error (use-package turbo-log :quelpa (turbo-log :fetcher github :repo "artawower/turbo-log.el") :config (setq turbo-console--prefix "✰"))) (bind-key* "C-x l" #'my/turbo-log-hydra/body) (defhydra my/turbo-log-hydra (:color blue :hint nil) ("l" turbo-log-print "Log selected expression" :column "TurboLog: Insert meaningful log message for selected expressions") ("c" turbo-log-comment-all-logs "Comment out all logs") ("u" turbo-log-uncomment-all-logs "Uncomment out all logs") ("d" turbo-log-delete-all-logs "Delete all TurboLog logs") ("q" nil "Cancel")) (defun turbo-log--ecmascript-print (current-line-number formatted-selected-text prev-line-text multiple-logger-p) "Console log for ecmascript, js/ts modes. CURRENT-LINE-NUMBER - line number under cursor FORMATTED-SELECTED-TEXT - formatted text without space at start position PREV-LINE-TEXT - text from previous line MULTIPLE-LOGGER-P - should guess list of available loggers?" (let* ((is-empty-body (turbo-log--ecmascript-empty-body-p (turbo-log--get-line-text current-line-number))) (insert-line-number (turbo-log--ecmascript-find-insert-pos current-line-number prev-line-text)) (meta-info (turbo-log--format-meta-info insert-line-number)) (normalized-code (turbo-log--ecmascript-normilize-code formatted-selected-text)) (turbo-log--message (concat (turbo-log--choose-logger turbo-log--ecmascript-loggers multiple-logger-p) "('" meta-info formatted-selected-text ": ', " ;; HACK this is my change: Does the TurboLog prefix have a %c console styling marker? If so, use it. (if (s-contains? "%c" meta-info) "'color: green; font-weight: bold;', " "") normalized-code ")" (if (plist-get turbo-log--ecmascript-configs :include-semicolon) ";")))) (if is-empty-body (progn (turbo-log--goto-line (- current-line-number 1)) (beginning-of-line) (search-forward-regexp "}[[:blank:]]*") (replace-match "") (turbo-log--insert-with-indent current-line-number turbo-log--message) (turbo-log--insert-with-indent (+ current-line-number 1) "}") (indent-according-to-mode)) (turbo-log--insert-with-indent insert-line-number turbo-log--message)))) ) #+end_src **** TODO ll-debug :PROPERTIES: :CUSTOM_ID: ll-debug :END: # ~ Useful when no debugger setup [[https://melpa.org/#/ll-debug][ll-debug.el]] provides commands to support a low level debug style. It features quick insertion of various debug output statements and improved functions for commenting and uncommenting chunks of code. #+begin_quote I don't use debuggers very much. I know they can be a big help in some situations and I tried some of them, but I find it almost always more direct/convenient/enlightening to put a quick 'printf' into a critical area to see what is happening than to fire up a big clumsy extra program where it takes me ages just to step through to the interesting point. In order to avoid repeated typing of 'printf("I AM HERE\n");' and similar stuff, I created `ll-debug-insert'. It inserts a statement into your sourcecode that will display a debug message. It generates unique messages on each invocation (the message consists of a big fat DEBUG together with a counter and the current filename). ---ll-debug.el #+end_quote #+begin_src emacs-lisp ;; C-u C-v C-d ⇒ Log a message, printing values of expressions. ;; E.g., in JS this prints, console.log("DEBUG-5-del.js"," 1 + 3:",1 + 3); ;; Note “5” is the fifth debug message, and “del.js” is the name of the buffer. ;; Works with Rust, Java, Lisps, JS, TS, Clojure, C/C++, Ruby, Matlab/Octave, Shell, Perl. (use-package ll-debug :config (bind-key "C-x l" (lambda () (interactive) (ll-debug-insert 1)) #'prog-mode-map)) ;; See variable `ll-debug-statement-alist' if you want to know which ;; modes are currently supported by ll-debug. You can add new modes ;; with `ll-debug-register-mode'. ;; ;; If you want to get rid of the debug messages, use ;; `ll-debug-revert'. It finds and removes the lines with the debug ;; output statements, asking for confirmation before it removes ;; anything. #+end_src *** ~M-x jsdoc~: Insert JSDocs with minimal type inference, useful with LSP-mode :PROPERTIES: :CUSTOM_ID: COMMENT-M-x-jsdoc-Insert-JSDocs-with-minimal-type-inference-useful-with-LSP-mode :END: Let's make use of JSDocs for functions ---since then LSP will show us the types and function description in a neato pop-up to the side. [[https://github.com/isamert/jsdoc.el][jsdoc.el]] inserts JSDoc function comments/typedefs easily; it also tries to infer types by itself while doing that. #+begin_src emacs-lisp ;; [Minimal Type Inference] When default values are provided, then we can infer ;; the type of the arguments. ;; ;; Use: Run “M-x jsdoc” on a JS function. ;; (use-package jsdoc :quelpa (jsdoc :fetcher github :repo "isamert/jsdoc.el") :config (use-package tree-sitter) ;; Required dependencies (use-package tree-sitter-langs) :hook (js-mode . tree-sitter-mode)) #+end_src *** Cucumber :PROPERTIES: :CUSTOM_ID: Cucumber :END: #+begin_src emacs-lisp ;; Emacs mode for editing Cucumber plain text stories ;; “.feature” files now open up with nice colouring. (use-package feature-mode) ;; ;; C-c ,g Go to step-definition under point (requires ruby_parser gem >= 3.14.2) ;; ;; TODO: Ruby specific; but the source could be edited to work for JS. ;; (use-package cucumber-goto-step) #+end_src Other packages to consider looking into include: - [[https://github.com/scottaj/mocha.el][mocha.el: Emacs mode for running mocha tests]] - [[https://github.com/Emiller88/emacs-jest][emacs-jest: A package to run jest inside emacs]] *** JavaScript :Does_not_work_with_flow: :PROPERTIES: :CUSTOM_ID: COMMENT-JavaScript :END: Let's get a JavaScript refactoring library for emacs: #+begin_src emacs-lisp :tangle no :tangle work_secrets.el ;; (use-package js2-mode) (use-package js2-refactor ;; Does not work with flow.js :'( :hook (js-mode . js2-refactor-mode) :config (js2r-add-keybindings-with-prefix "s-j")) ;; To be aware of https://github.com/azer/npm.el ;; Create and rule NPM packages from Emacs #+end_src Using ~⌘ j~ then one of the following... | ~lt~ | Adds a console.log() statement for what is at point (or region). | | | With a prefix argument, use JSON pretty-printing. | | ~dt~ | Adds a debug() statement for what is at point (or region). | | ~k~ | is kill: Kills to the end of the line, but does not cross semantic boundaries. | |----+--------------------------------------------------------------------------------| | ~ee~ | Make an inline list/object/function/funcall be on multiple lines | | ~cc~ | Opposite of ee | |----+--------------------------------------------------------------------------------| | ~tf~ | Toggle between ~function name() {}~ and ~var name = function () {}~ | | ~ta~ | Toggle between function expression to arrow function | | ~ts~ | Toggle between an async and a regular function. | |----+--------------------------------------------------------------------------------| | ~ef~ | Extract the currently selected expression into a top level function | | ~em~ | Like ef, but it's a method in the parent/ambient class | | ~ev~ | Takes a marked expression and replaces it with a var | | ~el~ | Similar to extract-var but uses a let-statement | | ~ec~ | Similar to extract-var but uses a const-statement | | ~iv~ | Opposite of iv: Replaces all instances of a variable with its initial value | | ~vt~ | Changes local var a to be this.a instead, and all lexical uses. | | ~rv~ | Renames the variable on point and all occurrences in its lexical scope | |----+--------------------------------------------------------------------------------| | ~wi~ | Wraps the entire buffer in an immediately invoked function expression | | ~3i~ | Converts ternary operator to if-statement; nice! | | ~ss~ | Split a string, at point, into a catenation of strings | | ~st~ | Convert a string into a `template`. | ** Outshine: Org outlining everywhere :PROPERTIES: :CREATED: [2025-08-28 Thu 20:08] :END: Features: + Navigate through code buffers via headings like you do with org buffers + Edit comments under outline headings in separate org-mode buffers Once one gets used to Org-mode, it's hard to live without it. Even its most basic feature, the hierarchical tree-like structuring of files, can be missed badly when editing files in other GNU Emacs major-modes, not to mention the convenient navigation, structure-editing and visibility-cycling functionality Org-mode offers for these tree-like structures. #+begin_details "My use case: Writing org-special-block-extras.el" My use case is writing Lisp packages for submission to Melpa. I initially tried to write them using Literate Programming ---within Org and using src blocks--- but that didn't scale very well for me when I exceeded 8k lines, with only 2k being code. There was too much prose beside the code (including tests). Perhaps I should have split the prose into multiple documents. Anyhow, now I'm trying to write 3 files: Docs in Org, code in Lisp, and tests in Lisp. The separation of concerns is nice. Moreover, my docstrings in Lisp code are lengthy, so I'm still being ‘literate’. #+end_details + Outshine attempts to bring the look and feel of Org Mode to the world outside of the Org major-mode: /We get the nice-looking collapsible outline headings everywhere, and can edit comments as Org./ + An outshine buffer is structured like an org-mode buffer, only with “outcommented headlines”: Headings are comments. + “Outorg” is for editing comment-sections of source-code files in temporary Org-mode buffers. That is all. (Inverse Literate Programming.) Often times, I have lengthy comments and it'd be nice to edit them as Org; e.g., to easily create lists and to rearrange them with auto renumbering. Another package that does editing with Org-mode in other major-modes is called =poporg=, but it does not look as nice nor behave as well as outorg; e.g., only doc at point is considered, not the entire tree at point. However, the fact that poporg edits stand-alone comments and strings means it's ideal for when I want to edit the /docstring/ of a method in Org-mode. I already do this with ~⌘-e~ using ~separedit~. #+begin_src emacs-lisp (use-package outshine :hook emacs-lisp-mode ;; Press “?” on a heading to see what you can do with it. ;; ⇒ “n/p/f/b” to navigate; “r/w” to restrict/widen; “j/J” to navigate in-detail. ;; Also note: M-x outline-show-entry :custom (outshine-use-speed-commands t) ;; Make “⌘-e” enter “Edit as Org” ;; Note: “C-u ⌘-e” transforms the entire code buffer into an Org buffer. Nice if you want to export code to, say, an Org blog article 😉 :bind (:map emacs-lisp-mode-map ("s-e" . outorg-edit-as-org) ;; “C-x n d” narrows to defun; “C-x n s” narrows to subtree (from anywhere inside it) ("C-x n s" . (lambda () (interactive) (unless (outline-on-heading-p) (outline-previous-heading)) (outshine-narrow-to-subtree))) :map outorg-edit-minor-mode-map ("C-x C-s" . outorg-copy-edits-and-exit))) ;; 😲 Very useful: ;; M-⇆ is used to incrementally show (→) or hide (←) content of the current heading. ;; M-↕ is used to navigate between headings ;; M-S-⇆ is used to demote/promote headings ;; M-S-↕ is used to move headings ;; S-TAB cycle through entire buffer visibility ;; TAB cycle though visibility of current heading ;; Get a birds’ eye view (when I open a file). (add-hook 'outline-minor-mode-hook (defun my/outline-overview () "Show all headings but no content in Outline mode." (interactive) ;; (outline-show-all) (outline-hide-body) (unless (or (s-starts-with? "*Org Src init.org[ emacs-lisp ]*" (buffer-name)) (s-contains? (f-expand user-emacs-directory) default-directory)) (-let [current-prefix-arg 16] (outshine-cycle-buffer))))) #+end_src The “J” key invokes “navi-mode”, which is essentially the built-in “occur-mode” specialised for use with Outshine. We can also enter it with “M-s n”. - In this buffer, we can then run “navigational queries” such as + pressing keys 1-8 to see headings at levels 1…8 + “f” to see functions or “v” to see variables, + “a” to see all Lisp declarations, + “C-3 a” to see all declarations down to 3 headings, + or “M” for macros, or “h” for other things to look at quickly in an Elisp file. - On headings, we can press “TAB” to cycle visiblity, or “+/-” to promote/demote them; or “^/<” to move a heading up/down, or “e” to edit as Org-mode. - Workflow: “3” to see all headings up to level 3, then “r” to restrict/narrow view to one in particular, then “a” to see all declaration therein. - See also doc:navi-key-mappings and doc:navi-keywords. Note: Navi-mode is similar to doc:org-goto, or kbd:C-c_C-j, for finding something in your file /without/ losing where you currently are. 🤔 Thinking “program = code + prose” means we can have prose as the main thing and code as a second-class citizen (i.e., Org-mode) or we can have code be the main thing and prose be the second-class citizen (i.e., code with comments). The Outshine Project lets us switch between the two views: We write code, and when we want to edit a section, we switch to Org-mode: All comments become first-class text, and code becomes “src” blocks. When switching from a programming-mode to org-mode, the comments are converted to text and the source-code is put into src-blocks. When switching back from org-mode to the programming-mode, the process is reversed - the text is outcommented again and the src-blocks that enclose the source-code are removed. An alternative stack includes: + [[https://www.reddit.com/r/emacs/comments/e2u5n9/code_folding_with_outlineminormode/][Code folding with outline-minor-mode]] ---and the [[https://www.gnu.org/software/emacs/manual/html_node/emacs/Outline-Format.html][official docs]] + [[https://github.com/tarsius/bicycle][GitHub - tarsius/bicycle: Cycle outline and code visibility]] + [[https://github.com/tarsius/backline][GitHub - tarsius/backline: Preserve appearance of collapsed outline headings until right window edge]] + [[https://github.com/tarsius/outline-minor-faces][GitHub - tarsius/outline-minor-faces: Heading faces for outline-minor-mode]] + 🤔 [[https://stackoverflow.com/a/1211325][Folding is generally unnecessary with Emacs - Stack Overflow]] Also to be aware of: + [[https://elpa.gnu.org/packages/orgalist.html][GNU ELPA - orgalist]] Manage Org-like lists in non-Org buffers Finally, Major programming modes show comments and strings in full, and when these comments or strings are written using Org, with all parts of a link visible, it may be disruptive to those sensible to line width limits. The nice [[https://github.com/seanohalpin/org-link-minor-mode][org-link-minor-mode]] package takes good care of this, by hiding the usually invisible parts of an Org link in other modes. #+begin_src emacs-lisp :tangle no (url-copy-file "https://raw.githubusercontent.com/seanohalpin/org-link-minor-mode/refs/heads/master/org-link-minor-mode.el" "~/.emacs.d/elpa/org-link-minor-mode.el" :ok-if-already-exists) (load-file "~/.emacs.d/elpa/org-link-minor-mode.el") (add-hook 'emacs-lisp-mode-hook 'org-link-minor-mode) #+end_src TODO: This does not seem to work as intended. So, if Outshine and Org-mode are two ways to do Literate Programming, why prefer one over the other? It depends on the task at hand, when programming I prefer Outshine since I can easily invoke refactoring methods ---e.g., rename a symbol across all uses--- but when writing a blog article, I prefer Org-mode for its prose support. ** Reduce cognitive attention from Lisp parentheses :PROPERTIES: :CREATED: [2025-08-29 Fri 08:59] :END: Make parentheses less visible in Lisp code by dimming them. We lispers probably don't need to be constantly made aware of the existence of the parentheses. #+begin_src emacs-lisp ;; By default parentheses and brackets are dimmed, customize option `paren-face-regexp' if you also want to dim braces or don't want to dim brackets. (use-package paren-face :hook (emacs-lisp . my/dim-parens-instead-of-drawing-attention-to-them-via-rainbow-colouring)) (defun my/dim-parens-instead-of-drawing-attention-to-them-via-rainbow-colouring () (rainbow-delimiters-mode -1) (paren-face-mode +1)) #+end_src # Image: Blurring away parentheses [[https://github.com/tarsius/paren-face/raw/88cbcf779d3c382cf785a540a2134a663b753d7b/parentheses.png]] ** Refactoring: Rename fun, inline fun, extract fun, extract constant, etc :PROPERTIES: :CREATED: [2025-09-09 Tue 05:20] :END: #+begin_src emacs-lisp (use-package emr ;; 𝑬𝑴acs 𝑹refactor ;; Press “⌘-ENTER” to get a drop-down of relevant refactors. Select a region or else use thing at point. ;; NOTE: With hyperbole enabled in prog-mode, M-RET is “/smart/ jump to definition”: ;; This is like “M-.” but is smart enough to realize 'foo should jump to the form (defun foo …). :bind (:map prog-mode-map ("s-
Of note:
+ Multiline comments are with ~/' comment here '/~, single quote starts a one-line comment.
+ Nodes don't need to be declared, and their names may contain spaces if they are enclosed in double-quotes.
+ One forms an arrow between two nodes by writing a line with ~x ->[label here] y~
or ~y <- x~; or using ~-->~ and ~<--~ for dashed lines. The label is optional.
To enforce a particular layout, use ~-X->~ where ~X ∈ {up, down, right, left}~.
+ To declare that a node ~x~ has fields ~d, f~ we make two new lines having
~x : f~ and ~x : d~.
+ One adds a note near a node ~x~ as follows: ~note right of x: words then newline\nthen more words~.
Likewise for notes on the ~left, top, bottom~.
- A note can be on several lines. It's terminated by ~end note~.
+ Interesting sprites and many other things can be done with PlantUML. Read the docs.
This particular workflow is inspired by [[http://doc.norang.ca/org-mode.html][Bernt Hansen]] ---while quickly searching
through the PlantUML [[http://plantuml.com/guide][manual]]: The above is known as an “activity diagram” and
it's covered in §4.
Org-mode may be used with PlantUML:
+ See §11,12 for using Org-mode notation to form ‘mindmaps’ and ‘work breakdown
structures’.
+ Org-mode text formatters are also acknowledged but the delimiters must be
doubled; see §16.1.
You can quickly write and see the resulting UMLs using
https://liveuml.com/, for the most part.
** [#C] COMMENT ON_STARTED, ON_DONE, ON_XYZ
:PROPERTIES:
:CREATED: [2024-05-09 Thu 08:01]
:END:
#+begin_src emacs-lisp
;; Run hooks “ON_[STARTED∣DONE]” state changes.
;; (MA: Consider adding “ON_𝒳” for all states 𝒳, using above workflow loop.)
;; (MA: Consider turning the example /below/ into a single property hook, say “:TEMPORARILY_TREAT_SUBTREES_AS_CHECKBOXES: t”)
;;
;; For example, in the following, when we press “t s” to put “A” into “STARTED A” the declared code is run:
;; It essentially treats all children trees, temporarily, as checkboxes: Pressing “t” toggles between “ ∣ TODO ∣ DONE”
;; and does not log any info about state change of the subtrees. (Also, the “STARTED A” is becomes “A”).
;; Then when we press “t” on “A” we get “DONE A”, which invokes the associated ON_DONE code, which just resets things to before
;; we began working on task “A”.
;;
;; ** A
;; :PROPERTIES:
;; :ON_STARTED: (progn (if (search-forward-regexp org-todo-regexp nil t) (or (delete-region (match-beginning 0) (match-end 0)) t)) (setq remember/org-todo-keywords org-todo-keywords) (setq org-todo-keywords '("TODO" "DONE")) (setq remember/org-log-done org-log-done) (setq org-log-done nil) (org-mode-restart))
;; :ON_DONE: (progn (setq org-todo-keywords remember/org-todo-keywords org-log-done remember/org-log-done) (org-mode-restart))
;; :END:
;;
;; *** TODO B
;;
(add-hook
'org-after-todo-state-change-hook
(defun my/special-ON_STARTED-property-hook ()
"When a task enters STARTED/DONE state, execute the code in its ON_STARTED/ON_DONE property."
(save-excursion
(save-restriction
;; yet another property support
(when (equal (org-get-todo-state) "TODO")
;; Instead of ignore-errors, it should only evaluate the string /if/ it is present.
(ignore-errors (eval (car (read-from-string (eval (org-entry-get (point) "ON_TODO")))))))
;; yet another property support
(when (equal (org-get-todo-state) "STARTED")
;; Instead of ignore-errors, it should only evaluate the string /if/ it is present.
(ignore-errors (eval (car (read-from-string (eval (org-entry-get (point) "ON_STARTED")))))))
;; yet another property support
(when (equal (org-get-todo-state) "DONE")
;; Instead of ignore-errors, it should only evaluate the string /if/ it is present.
(ignore-errors (eval (car (read-from-string (eval (org-entry-get (point) "ON_DONE")))))))
;; yet another property support -- AXE?
(when (equal "t" (org-entry-get (point) "TEMPORARILY_TREAT_SUBTREES_AS_CHECKBOXES"))
(when (equal (org-get-todo-state) "TODO")
(let ((current-prefix-arg :random-theme)) (my/toggle-theme))
(org-narrow-to-subtree)
(beginning-of-buffer)
(setq remember/org-todo-keywords org-todo-keywords
org-todo-keywords '("TODO" "DONE")
remember/org-log-done org-log-done
org-log-done nil
remember/org-log-note-headings org-log-note-headings
org-log-note-headings nil)
(org-mode-restart))
(when (or (equal (org-get-todo-state) "DONE") (equal (org-get-todo-state) ""))
(setq org-todo-keywords remember/org-todo-keywords
org-log-done remember/org-log-done
org-log-note-headings remember/org-log-note-headings)
(org-mode-restart)))))))
#+end_src
#+RESULTS:
| my/special-ON_STARTED-property-hook | my/remove-schedule--WAITING |
** TODO COMMENT Music for DONE state
:PROPERTIES:
:CREATED: [2025-01-10 Fri 15:33]
:END:
- *Music and sound effects:* There is a reason that chimes and trumpets
sound when you successfully perform a task or reach a goal in a
videogame or slot machine. Pleasure is a reward, and pleasant sights
and sounds produce pleasure.
* ✏️ Capturing Content: Links, Smart Paste, Attachments, and Org Rifle
:PROPERTIES:
:CREATED: [2025-04-14 Mon 09:43]
:END:
** Capture: Now that I know how to query my agenda, how do I get things into it efficiently?
:PROPERTIES:
:CREATED: [2025-04-14 Mon 09:29]
:END:
An important part of any organization system is the ability to quickly /capture/ new ideas and tasks, and to associate
reference material with them. It also can store files related to a task (/attachments/) in a special directory. Finally,
it can parse RSS feeds for information.
It is often useful to associate reference material with an outline node. Small chunks of plain text can simply be
stored in the subtree of a project. Hyperlinks (see [[https://orgmode.org/manual/Hyperlinks.html][Hyperlinks]]) can establish associations with files that live
elsewhere on a local, or even remote, computer, like emails or source code files belonging to a project. Another method
is [[https://orgmode.org/manual/Attachments.html][/attachments/]], which are files located in a directory belonging to an outline node.
#+begin_src emacs-lisp
(eval-and-compile (require 's nil t)) ;; Needed for s-replace-regexp in def-capture macro
(declare-function s-replace-regexp "s" (regexp replacement s &optional literal))
(declare-function s-contains\? "s" (needle s &optional ignore-case))
(declare-function s-replace "s" (old new s))
(declare-function s-trim "s" (s))
(cl-defmacro def-capture (name location template &rest forms)
"Creates a method “my/capture-NAME”, which opens a capture buffer named NAME showing TEMPLATE.
When you press `C-c C-c`, the note is saved as an entry (ie TEMPLATE should start with “* ”.)
in `org-default-notes-file' section named LOCATION.
+ NAME, LOCATION, TEMPLATE are all strings that may contain spaces.
⇒ If you want to evaluate a function in TEMPLATE and have its results be inlined, use the syntax “%(f args)”.
See https://stackoverflow.com/a/69331239 for an example.
⇒ See the docs of `org-capture-templates', half-way down, for supported %-escapes in the template.
+ FORMS is an optional collection of Elisp forms to execute after a capture template session has been initiated;
e.g., to programmatically add content to a template, say a quote or the results of a shell command.
+ Example: (def-capture \"Friends Info\" \"Journal\" \"* %t\" (message \"Well-done! Stay in touch!\"))
This can be used as “M-x my/capture-friends-info” or via an Org link: “[[elisp:( my/capture-friends-info)]]”.
Note: My “Journal” is nested in a section called “Workflow”, and capture finds it anyways (｡◕‿◕｡)
(More precisely, Org-Capture looks for the first (sub)headline called “Journal” /anywhere/ and uses that as the target location.)
Usage:
1. M-x my/capture-NAME ⇒ Capture something to my LOCATION; no menu used.
2. C-u M-x my/capture-NAME ⇒ Jump to my LOCATION.
3. C-u C-u M-x my/capture-NAME ⇒ Goto last note stored (by any my/capture-* method).
"
`(defun ,(intern (concat "my/capture-" (replace-regexp-in-string " " "-" (downcase name)))) (&optional prefix)
(interactive "p")
(let (;; Temporarily pause any clocking hooks
(org-clock-in-hook nil)
(org-clock-out-hook nil)
(org-capture-templates
;; Capture mode now handles automatically clocking in and out of a capture task.
;; When I start a capture mode task the task is clocked in as specified by :clock-in t
;; and when the task is filed with C-c C-c the clock resumes on the original clocking task.
`(("𝒞" ,,name entry (file+headline "~/Dropbox/my-life.org" ,,location) ,,template :clock-in t :clock-resume t))))
(org-capture (list prefix) "𝒞")
(unless (> prefix 1) (rename-buffer ,name))
,@forms)))
(unless noninteractive
(eval '(bind-key* "C-c c" (def-capture "Inbox Entry 📩" "Inbox 📩 \t\t\t:inbox:" "* TODO %?\n:PROPERTIES:\n:CREATED: %U\n:END:\n"))))
#+end_src
My other primary use of ~def-capture~ is for 〔Daily ∣ Weekly ∣ Monthly ∣ Bi-Annual〕reviews.
** Persistent Scratch Buffer :Disabled:
:PROPERTIES:
:CUSTOM_ID: Persistent-Scratch-Buffer
:header-args: :tangle no
:END:
The ~*scratch*~ buffer is a nice playground for temporary data or experiments.
However, by default its contents are not saved --which may be an issue if we
have not relocated our playthings to their appropriate files. Whence let's save
& restore the scratch buffer by default.
#+begin_src emacs-lisp
(use-package persistent-scratch
;; In this mode, the usual save key saves to the underlying persistent file.
:bind (:map persistent-scratch-mode-map ("C-x C-s" . persistent-scratch-save)))
#+end_src
We might accidentally close this buffer, so we could utilise the following.
#+begin_src emacs-lisp
(defun scratch ()
"Recreate the scratch buffer, loading any persistent state."
(interactive)
(switch-to-buffer-other-window (get-buffer-create "*scratch*"))
(condition-case nil (persistent-scratch-restore) (insert initial-scratch-message))
(org-mode)
(persistent-scratch-mode)
(persistent-scratch-autosave-mode 1))
;; This doubles as a quick way to avoid the common formula: C-x b RET *scratch*
;; Upon startup, close the default scratch buffer and open one as specfied above
(ignore-errors (kill-buffer "*scratch*") (scratch))
#+end_src
I use Org-mode often, so that's how I want things to appear.
#+begin_src emacs-lisp
(setq initial-scratch-message (concat
"#+title: Persistent Scratch Buffer"
"\n#\n# Welcome! This’ a place for trying things out."
"\n#\n# ⟨ ‘C-x C-s’ here saves to ~/.emacs.d/.persistent-scratch ⟩ \n\n"))
#+end_src
** Adding New *Tasks/Notes* Quickly Without Disturbing The Current Task Content
New sections can be created conveniently by simply modifying the ~RETURN~ key:
+ M-RET :: New Org item, if near an itemisation; else a new heading /here/.
+ M-S-RET :: New Org checkbox, if near an itemisation; else a new ~TODO~ heading /here/.
+ C-RET :: New Org heading /after/ the current section.
+ C-S-RET :: New ~TODO~ heading /after/ the current section.
For example, in the middle of an entry I can press ~C-RET~ to make a new heading
/at the end/ of the current entry. Alternatively, I can /split/ the current entry in
the middle with ~M-RET~.
Finally, every time I create a heading using a modified ~RETURN~, I automatically
insert an inactive timestamp indicating when the headline is created (unless I
press ~C-u~ first).
#+begin_src emacs-lisp
(add-hook
'org-insert-heading-hook
(defun my/insert-CREATED-property ()
"Insert :CREATED: property upon C-[S]-RET and M-[S]-RET, unless C-u is pressed first."
(unless current-prefix-arg
(org-set-property "CREATED" (format-time-string "[%Y-%m-%d %a %H:%M]")))))
;; I also have a short cut key defined to invoke this function on demand so that
;; I can insert the inactive timestamp anywhere on demand.
;;
;; I use TAB and S-TAB for cycling - I don't need c and C as well.
;; Instead use “c” to add the ‘C’reated property.
(setf (cdr (assoc "c" org-speed-commands)) #'my/insert-CREATED-property)
#+end_src
Finally, when I'm working in a itemisation, I usually want an /indented/ newline whenever I
press ~RETURN~.
#+BEGIN_SRC emacs-lisp
(add-hook 'org-mode-hook '(lambda ()
(local-set-key (kbd "%s
%s~ and horizontal rules via ~
~. Similarly you can use other HTML tags such as ~
-->B~. *Warning*: JavaScript has some issues when working with Unicode and so, being a JavaScript utility, ~mermaid~ hangs when Unicode is used. On the upside, being a JavaScript utility, ~mermaid~ entities can have [[https://mermaid-js.github.io/mermaid/#/flowchart?id=interaction][arbitrary code attached]] to them to be executed upon clicks ---for use in browsers. - However, the Greek letters are supported; e.g., γ and Σ. See [[https://mermaid-js.github.io/mermaid/#/flowchart?id=nodes-amp-shapes][here]] for possible node shapes. #+begin_quote After forming an intricate diagram of related design patterns, I had to use a number of HTML notions, such as =, , ,
, ,
, ,
= and it was a bit more than I would have liked. In particular, the only
way to change font size was to use the deprecated HTML tag == or heading tags
like ==; even worse, the resulting PDF image did not look nice ---I had to
stretch it out.
The command line tool is *lacking functionality* and so the docs are not helpful.
E.g., I cannot produce pie charts using the command line tool.
#+end_quote
**** [[https://revealjs.com/?transition=zoom#/][Reveal.JS]] -- The HTML Presentation Framework :Disabled:I_enable_this_as_I_need_it:See_also_Dslide:
:PROPERTIES:
:CUSTOM_ID: https-revealjs-com-transition-zoom-Reveal-JS-The-HTML-Presentation-Framework
:header-args: :tangle no :eval no-export
:END:
Org-mode documents can be transformed into beautiful slide decks
with [[https://github.com/yjwen/org-reveal/blob/master/Readme.org][org-reveal]] with the following two simple lines.
#+BEGIN_SRC emacs-lisp
(use-package ox-reveal
:custom (org-reveal-root "https://cdn.jsdelivr.net/npm/reveal.js"))
#+END_SRC
# MA: ??? It looks like ox-reveal is being abandoned in favor of org-re-reveal,
# a fork compatible with org-mode 9.2?
For example, execute, ~C-x C-e~ after the closing parenthesis of, the
following block to see an example slide-deck (─‿‿─)
#+BEGIN_SRC emacs-lisp :tangle no
(progn (shell-command "curl https://raw.githubusercontent.com/yjwen/org-reveal/696613edef0fe17a9c53146f79933fe7c4101100/Readme.org >> Trying_out_reveal.org")
(switch-to-buffer (find-file "Trying_out_reveal.org"))
(org-reveal-export-to-html-and-browse))
#+END_SRC
Org-mode exporting, ~C-c C-e~, now includes an option ~R~ for such reveal slide decks.
:Hide:
[[https://alhassy.github.io/next-700-module-systems/proposal/defence-slides.html#/sec-title-slide][Here]] ([[https://raw.githubusercontent.com/alhassy/next-700-module-systems/master/proposal/defence-slides.org][source]]) is an example of org-reveal slides where I add a number to each page,
use multiple columns, and extend the margins perhaps a bit too much.
:End:
Two dimensional slides may be a bit new to some people, so I like to
give viewers an option, in tiny font, to view the slide-deck
continuously and remind them that ~?~ provides useful shortcuts.
#+BEGIN_SRC emacs-lisp
(setq org-reveal-title-slide "%t
%a
⟪ Flattened View ; Press ? for Help ⟫
")
#+END_SRC
One should remove the ~&showNotes=true~ if they do not want to include
speaker notes in the flattened view.
Within the flatenned view, one may wish to ~CTRL/CMD+P~ then save the
resulting PDF locally.
*** TODO COMMENT Working with PDFs :Disabled:
**** TODO Open PDFs in Emacs
#+begin_src emacs-lisp
;; In Org-mode, clicking on PDF should open it in Emacs
;; Example: [[~/Desktop/stuff-I'm-learning.pdf::12]] ;; Opens the pdf to page 12
;; Another Example: docview:~/Desktop/stuff-I'm-learning.pdf::12
(ignore-errors (add-to-list 'org-file-apps '("\\.pdf\\'" . emacs)))
;; Required code to make the above links work as expected.
;; Source: https://www.reddit.com/r/emacs/comments/re0dx8/how_do_you_link_a_specific_pdf_page_in_org_mode/
(defun my-org-docview-open-hack (orig-func &rest args)
(let* ((link (car args)) path page)
(string-match "\\(.*?\\)\\(?:::\\([0-9]+\\)\\)?$" link)
(setq path (match-string 1 link))
(setq page (and (match-beginning 2)
(string-to-number (match-string 2 link))))
(org-open-file path 1)
(when page
(cond
((eq major-mode 'pdf-view-mode)
(pdf-view-goto-page page))
(t
(doc-view-goto-page page))))))
(advice-add 'org-docview-open :around #'my-org-docview-open-hack)
;; Alternatively, there's a dedicated package for this
;; https://github.com/fuxialexander/org-pdftools/tree/967f48fb5038bba32915ee9da8dc4e8b10ba3376
#+end_src
**** TODO The evils of this world
:PROPERTIES:
:CUSTOM_ID: The-evils-of-this-world
:END:
#+begin_src emacs-lisp :tangle no
;; “PDF” stands for Portable Document Format, since you should be able to open
;; it anywhere. Disgustingly, fillable PDF's made with Adobe can only be
;; smoothly opened & printed in Adobe ---Chrome can open them, but not print
;; them. Unfortunately, various government & insurance forms are only provided in
;; this format.
(system-packages-ensure "adobe-acrobat-reader")
#+end_src
*** TODO COMMENT Makes Org/Markdown previewabvle as we type!!! ♥
:PROPERTIES:
:CUSTOM_ID: Makes-Org-Markdown-previewabvle-as-we-type
:END:
#+begin_src emacs-lisp :tangle no
;; Shows up as a magnifying glass in doom-modeline.
(use-package grip-mode)
;; :hook ((markdown-mode org-mode) . grip-mode)
;; Pretty annyoning actually; instead we should call it as needed.
)
#+end_src
*** COMMENT Makeshift HTML Folded Drawers: Folding-mode & Org-Macros
:PROPERTIES:
:CUSTOM_ID: Makeshift-HTML-Folded-Drawers-Folding-mode-Org-Macros
:END:
My =my/prettify-alist= has the following:
("{{{fold(" . ?↳)
(")}}}" . ?↲)
("{{{end-fold}}}" . ?↺)
The ~↳Title Here↲ Contents ↺~ combination is for my makeshift HTML code
folding macro ---word-wrapped for readability.
#+BEGIN_SRC org :tangle no
,#+MACRO: end-fold #+HTML:
=; even worse, the resulting PDF image did not look nice ---I had to
stretch it out.
The command line tool is *lacking functionality* and so the docs are not helpful.
E.g., I cannot produce pie charts using the command line tool.
#+end_quote
**** [[https://revealjs.com/?transition=zoom#/][Reveal.JS]] -- The HTML Presentation Framework :Disabled:I_enable_this_as_I_need_it:See_also_Dslide:
:PROPERTIES:
:CUSTOM_ID: https-revealjs-com-transition-zoom-Reveal-JS-The-HTML-Presentation-Framework
:header-args: :tangle no :eval no-export
:END:
Org-mode documents can be transformed into beautiful slide decks
with [[https://github.com/yjwen/org-reveal/blob/master/Readme.org][org-reveal]] with the following two simple lines.
#+BEGIN_SRC emacs-lisp
(use-package ox-reveal
:custom (org-reveal-root "https://cdn.jsdelivr.net/npm/reveal.js"))
#+END_SRC
# MA: ??? It looks like ox-reveal is being abandoned in favor of org-re-reveal,
# a fork compatible with org-mode 9.2?
For example, execute, ~C-x C-e~ after the closing parenthesis of, the
following block to see an example slide-deck (─‿‿─)
#+BEGIN_SRC emacs-lisp :tangle no
(progn (shell-command "curl https://raw.githubusercontent.com/yjwen/org-reveal/696613edef0fe17a9c53146f79933fe7c4101100/Readme.org >> Trying_out_reveal.org")
(switch-to-buffer (find-file "Trying_out_reveal.org"))
(org-reveal-export-to-html-and-browse))
#+END_SRC
Org-mode exporting, ~C-c C-e~, now includes an option ~R~ for such reveal slide decks.
:Hide:
[[https://alhassy.github.io/next-700-module-systems/proposal/defence-slides.html#/sec-title-slide][Here]] ([[https://raw.githubusercontent.com/alhassy/next-700-module-systems/master/proposal/defence-slides.org][source]]) is an example of org-reveal slides where I add a number to each page,
use multiple columns, and extend the margins perhaps a bit too much.
:End:
Two dimensional slides may be a bit new to some people, so I like to
give viewers an option, in tiny font, to view the slide-deck
continuously and remind them that ~?~ provides useful shortcuts.
#+BEGIN_SRC emacs-lisp
(setq org-reveal-title-slide "%t
%a
⟪ Flattened View ; Press ? for Help ⟫
")
#+END_SRC
One should remove the ~&showNotes=true~ if they do not want to include
speaker notes in the flattened view.
Within the flatenned view, one may wish to ~CTRL/CMD+P~ then save the
resulting PDF locally.
*** TODO COMMENT Working with PDFs :Disabled:
**** TODO Open PDFs in Emacs
#+begin_src emacs-lisp
;; In Org-mode, clicking on PDF should open it in Emacs
;; Example: [[~/Desktop/stuff-I'm-learning.pdf::12]] ;; Opens the pdf to page 12
;; Another Example: docview:~/Desktop/stuff-I'm-learning.pdf::12
(ignore-errors (add-to-list 'org-file-apps '("\\.pdf\\'" . emacs)))
;; Required code to make the above links work as expected.
;; Source: https://www.reddit.com/r/emacs/comments/re0dx8/how_do_you_link_a_specific_pdf_page_in_org_mode/
(defun my-org-docview-open-hack (orig-func &rest args)
(let* ((link (car args)) path page)
(string-match "\\(.*?\\)\\(?:::\\([0-9]+\\)\\)?$" link)
(setq path (match-string 1 link))
(setq page (and (match-beginning 2)
(string-to-number (match-string 2 link))))
(org-open-file path 1)
(when page
(cond
((eq major-mode 'pdf-view-mode)
(pdf-view-goto-page page))
(t
(doc-view-goto-page page))))))
(advice-add 'org-docview-open :around #'my-org-docview-open-hack)
;; Alternatively, there's a dedicated package for this
;; https://github.com/fuxialexander/org-pdftools/tree/967f48fb5038bba32915ee9da8dc4e8b10ba3376
#+end_src
**** TODO The evils of this world
:PROPERTIES:
:CUSTOM_ID: The-evils-of-this-world
:END:
#+begin_src emacs-lisp :tangle no
;; “PDF” stands for Portable Document Format, since you should be able to open
;; it anywhere. Disgustingly, fillable PDF's made with Adobe can only be
;; smoothly opened & printed in Adobe ---Chrome can open them, but not print
;; them. Unfortunately, various government & insurance forms are only provided in
;; this format.
(system-packages-ensure "adobe-acrobat-reader")
#+end_src
*** TODO COMMENT Makes Org/Markdown previewabvle as we type!!! ♥
:PROPERTIES:
:CUSTOM_ID: Makes-Org-Markdown-previewabvle-as-we-type
:END:
#+begin_src emacs-lisp :tangle no
;; Shows up as a magnifying glass in doom-modeline.
(use-package grip-mode)
;; :hook ((markdown-mode org-mode) . grip-mode)
;; Pretty annyoning actually; instead we should call it as needed.
)
#+end_src
*** COMMENT Makeshift HTML Folded Drawers: Folding-mode & Org-Macros
:PROPERTIES:
:CUSTOM_ID: Makeshift-HTML-Folded-Drawers-Folding-mode-Org-Macros
:END:
My =my/prettify-alist= has the following:
("{{{fold(" . ?↳)
(")}}}" . ?↲)
("{{{end-fold}}}" . ?↺)
The ~↳Title Here↲ Contents ↺~ combination is for my makeshift HTML code
folding macro ---word-wrapped for readability.
#+BEGIN_SRC org :tangle no
,#+MACRO: end-fold #+HTML:
$1
#+END_SRC :Example: # The (org-mode-restart) invocation actually enables the source block prettifications. # Empty macros to make the example go through. # #+MACRO: end-fold #+MACRO: fold {{{fold(nice)}}} hello {{{end-fold}}} :End: Let's have this fold-away in the source buffer as well by using [[https://www.emacswiki.org/emacs/FoldingMode][folding-mode]]; with show/hide with ~C-" "" verbatim)
("~" (:background "deep sky blue" :foreground "MidnightBlue"))
;; ("+" font-lock-comment-face)
("+" ( org-headline-done :strike-through t :foreground "grey"))))
;; Highlight things I write down, “MA: This is important, it's shown in a box; the period is the terminator.”
(add-hook 'org-font-lock-set-keywords-hook
(defun my/emphasize-MA-sentences ()
(add-to-list 'org-font-lock-extra-keywords
'("\\b\\(MA\\|TODO\\|NOTE\\).*\\." (0 '(:box t :foreground "#AAF"))))))
;; Text “!This text is in a purple box!”.
(add-hook 'org-font-lock-set-keywords-hook
(defun my/add/highlight-emphasis-via-! ()
(add-to-list 'org-font-lock-extra-keywords
'("\\(!\\)\\(.*\\)\\(!\\)"
(1 '(face nil invisible t))
(3 '(face nil invisible t))
(2 '(:box t :foreground "#AAF"))))))
;;
;;
;; TODO: Relocate this to org-special-block-extras.
;; Text “green:this-is-a-green-word”
(add-hook 'org-font-lock-set-keywords-hook
(defun my/add/green-emphasis ()
(add-to-list 'org-font-lock-extra-keywords
'("\\(green:\\)\\([^ ]*\\)"
(1 '(face nil invisible t))
(2 '(:foreground "green"))))))
#+end_src
TODO: Consider following this idea to have “inline tags” so I can easily click on them in a sentence;
e.g., “I use #emacs to write #org for the purposes of configuring my #life and #faith”.
** TODO Obtaining Values of ~#+KEYWORD~ Annotations :Disabled:MoveToBloggingSetup:AlBasmala:
:PROPERTIES:
:CUSTOM_ID: Obtaining-Values-of-KEYWORD-Annotations
:header-args: :tangle no
:END:
Org-mode settings are, for the most part, in the form ~#+KEYWORD: VALUE~. Of notable interest
are the ~TITLE~ and ~NAME~ keywords. We use the following ~org-keywords~ function to obtain
the values of arbitrary ~#+THIS : THAT~ pairs, which may not necessarily be supported by native
Org-mode --we do so for the case, for example, of the ~CATEGORIES~ and ~IMAGE~ tags associated with an article.
# Parse org buffer as an elisp structure: https://emacs.stackexchange.com/questions/2869/turn-a-list-or-data-structure-into-an-org-document#
#+begin_src emacs-lisp :tangle no
;; Src: http://kitchingroup.cheme.cmu.edu/blog/2013/05/05/Getting-keyword-options-in-org-files/
(defun org-keywords ()
"Parse the buffer and return a cons list of (property . value) from lines like: #+PROPERTY: value"
(org-element-map (org-element-parse-buffer 'element) 'keyword
(lambda (keyword) (cons (org-element-property :key keyword)
(org-element-property :value keyword)))))
(defun org-keyword (KEYWORD)
"Get the value of a KEYWORD in the form of #+KEYWORD: value"
(cdr (assoc KEYWORD (org-keywords))))
#+END_SRC
Note that capitalisation in a “#+KeyWord” is irrelevant.
See [[https://orgmode.org/manual/Org-syntax.html][here]] on how to see the abstract syntax tree of an org file
and how to manipulate it.
** Org-special-block-extras :Disabled_I_have_not_blogged_in_some_time:
MA: Enable this as part of AlBasmala.el, since that's really when I need it?
TODO: There's some TODOs below; are things not being defined at the right time?
Finally, let's get some extra Org-mode mark-up goodies, such as ~kbd:C-c_C-e~
which renders as kbd:C-c_C-e. Documentations and screenshots at:
https://alhassy.github.io/org-special-block-extras/
#+BEGIN_SRC emacs-lisp
(defun org-special-block-extras-short-names ())
;;
;; org-special-block-extras.el:681:1:Error: Symbol’s value as variable is void: o--supported-blocks
(setq o--supported-blocks nil)
;; TODO org-special-block-extras.el:681:1:Error: Symbol’s value as variable is void: o--supported-blocks
;;
(use-package org-special-block-extras
:hook (org-mode . org-special-block-extras-mode)
:custom
;; The places where I keep my ‘#+documentation’
(org-special-block-extras--docs-libraries
'("~/org-special-block-extras/documentation.org"))
;; Disable the in-Emacs fancy-links feature?
(org-special-block-extras-fancy-links
'(elisp badge kbd link-here doc tweet))
;; Details heading “flash pink” whenever the user hovers over them?
(org-html-head-extra (concat org-html-head-extra ""))
;; The message prefixing a ‘tweet:url’ badge
(org-special-block-extras-link-twitter-excitement
"This looks super neat (•̀ᴗ•́)و:")
:config
;; Use short names like ‘defblock’ instead of the fully qualified name
;; ‘org-special-block-extras--defblock’
(org-special-block-extras-short-names))
;; Let's execute Lisp code with links, as in “elisp:view-hello-file”.
(setq org-confirm-elisp-link-function nil)
#+END_SRC
** Password-locking files ---“encryption”
:PROPERTIES:
:CUSTOM_ID: Password-locking-files-encryption
:header-args: :tangle no
:END:
With the following incantation, we name our files ~𝒳.𝒴.gpg~ where 𝒳 is the file
name and 𝒴 is the usual extension, then upon save we will be prompted for an
encryption method, we can press kbd:Enter on ~OK~ to just provide a password for
that file. You can open that file /without/ the passphrase for a limited amount of
time ---i.e., it's cached, saved, for your current computing session until
logout--- or force authentication by invoking ~gpgconf --kill gpg-agent~.
#+begin_src emacs-lisp
(system-packages-ensure "gnupg") ;; i.e., brew install gnupg
;; “epa” ≈ EasyPG Assistant
;; Need the following in init to have gpg working fine:
;; force Emacs to use its own internal password prompt instead of an external pin entry program.
(setq epa-pinentry-mode 'loopback)
;; https://emacs.stackexchange.com/questions/12212/how-to-type-the-password-of-a-gpg-file-only-when-opening-it
(setq epa-file-cache-passphrase-for-symmetric-encryption t)
;; No more needing to enter passphrase at each save ^_^
;;
;; Caches passphrase for the current emacs session?
#+end_src
/The purpose of encrypting a file is so that an adversary/ ---e.g., an immoral
computer administrator or a thief who stole your computer--- /will have to spend
so much decrypting the data than the data is actually worth./ As such, one uses
GPG keys...!
#+begin_details GPG Details
Trivia: “gpg” stands for GnuPG, which abbreviates GNU Privacy Guard.
To obtain encrypted messages from others, you will need a “GPG key”: They use
/your/ “public key” (which others can see) to encrypt a file, which only /you/ can
open since you have the /associated/ “private key” (which only you see).
Possibly interesting reads:
+ [[https://www.bytedude.com/gpg-in-emacs/][GPG In Emacs | Bytedude]]
+ [[https://softwareengineering.stackexchange.com/questions/212192/what-are-the-advantages-and-disadvantages-of-cryptographically-signing-commits-a][What are the advantages and disadvantages of cryptographically signing commits and tags in Git? | Software Engineering Stack Exchange]]
#+end_details
** =README= ---From =init.org= to =init.el=
:PROPERTIES:
:CUSTOM_ID: README-From-init-org-to-init-el
:END:
Rather than manually extracting the Lisp code from this literate document each
time we alter it, let's instead add a ‘hook’ ---a method that is invoked on a
particular event, in this case when we save the file. More precisely, in this
case, ~C-x C-s~ is a normal save whereas ~C-u C-x C-s~ is a save after forming
~init.elc~ and ~README.md~.
**** The =my/make-init-el-and-README= function
:PROPERTIES:
:CUSTOM_ID: The-my-make-init-el-and-README-function
:END:
We ‘hook on’ the following function to the usual save method
that is associated with this file only.
# +name: enable making init and readme
#+name: startup-code
#+begin_src emacs-lisp :tangle no :eval never-export
(defun my/make-init-el-and-README ()
"Tangle an el and a github README from my init.org."
(interactive "P") ;; Places value of universal argument into: current-prefix-arg
(when current-prefix-arg
(let* ((time (current-time))
(_date (format-time-string "_%Y-%m-%d"))
(.emacs "~/.emacs")
(.emacs.el "~/.emacs.el"))
;; Make README.org
(save-excursion
(org-babel-goto-named-src-block "make-readme") ;; See next subsubsection.
(org-babel-execute-src-block))
;; remove any other initialisation file candidates
(ignore-errors
(f-move .emacs (concat .emacs _date))
(f-move .emacs.el (concat .emacs.el _date)))
;; Make init.el
(org-babel-tangle)
;; (byte-compile-file "~/.emacs.d/init.el")
(load-file "~/.emacs.d/init.el")
;; Acknowledgement
(message "Tangled, compiled, and loaded init.el; and made README.md … %.06f seconds"
(float-time (time-since time))))))
(add-hook 'after-save-hook 'my/make-init-el-and-README nil 'local-to-this-file-please)
#+end_src
**** The Org-block named =make-readme=
:PROPERTIES:
:CUSTOM_ID: The-Org-block-named-make-readme
:END:
Where the following block has ~#+NAME: make-readme~ before it. This source block
generates the ~README~ for the associated Github repository.
#+NAME: make-readme
#+begin_src emacs-lisp :tangle no :tangle no :export_never t
(save-buffer)
(with-temp-buffer
(insert
"#+EXPORT_FILE_NAME: README.org
# Logos and birthday present painting
,#+HTML:" (s-collapse-whitespace (concat
"
![](\"images/emacs-logo.png\"){kind=logo}
![](\"https://img.shields.io/badge/GNU%20Emacs-"){kind=icon}
![](\"https://img.shields.io/badge/org--mode-"){kind=icon}
![](\"images/emacs-birthday-present.png\")