Emacs - philnewton.net

Updated Pocket highlights bookmarklet

Mon, 07 Aug 2023 19:51:00 -0400

A couple of years ago I wrote a small bookmarklet for copying Pocket article highlights to an org-mode file. Pocket recently made some large updates to their site which modified the markup and broke the bookmarklet (and also ruined their iOS app).

I've written a new version of the bookmarklet. It works the same as before and will copy highlights to the clipboard, wrapped in org-mode quote blocks.

Drag the button below to your bookmarks toolbar, and then click it when viewing any highlighted article in Pocket to copy notes to the clipboard (tested in Firefox):

Copy Pocket Highlights

The un-minified source is below and can be modified to remove org-mode specific formatting if needed:

let to_clipboard   = "#+TITLE: " + document.getElementsByTagName('h1')[0].innerHTML + "\n\n";
const all_highlights = document.querySelectorAll('.sidebar-anchor aside > div > div > div > button');

all_highlights.forEach((highlight) => {
    if (highlight.classList.contains('inline-button') || highlight.hasAttribute('aria-label')) {
	return;
    }

    let highlight_text = highlight.innerHTML;
    if (typeof highlight_text !== 'undefined' && highlight_text.trim() != '') {
	to_clipboard += "#+begin_quote\n";
	to_clipboard += highlight_text.trim() + "\n";
	to_clipboard += "#+end_quote\n\n";
    }
});

to_clipboard += "*Source*: " + document.getElementById('reader.external-link.view-original').href;

navigator.clipboard.writeText(to_clipboard);

Filtering the Emacs dashboard agenda

Mon, 01 Nov 2021 07:42:00 -0400

I use emacs-dashboard to show an overview of my work when I start Emacs. It looks a little like this:

The weekly agenda gives me a quick glance of what's scheduled for the week ahead, as well as any upcoming deadlines, but I wanted to tweak it slightly to remove some non-useful information.

I use the WAITING keyword to mark tasks that are waiting on someone else and don't require my attention. I have a separate agenda command to show me all WAITING tasks and there's no need for these to show on my dashboard.

The dashboard package provides a couple of different ways to customize the agenda view. One of those is dashboard-match-agenda-entry, which uses org-mode's tag and property matching to filter tasks.

Limiting the dashboard agenda looks like this:

;; Match just one TODO keyword.
(setq dashboard-match-agenda-entry
      "TODO=\"TODO\"")

;; Match multiple keywords.
(setq dashboard-match-agenda-entry
      "TODO=\"TODO\"|TODO=\"IN-PROGRESS\"")

;; Match everything except WAITING.
(setq dashboard-match-agenda-entry
      "-TODO=\"WAITING\"")

There is a lot more to org-mode's matching system; I've used it to create custom views for displaying my monthly goals, but it can be used to match tags, categories, and even properties like Effort.

My Emacs Ledger reporting configuration

Mon, 25 Oct 2021 10:28:00 -0400

I've been using Ledger to keep track of my finances for several years, and one feature I really like is the ability to run reports from within Emacs via ledger-mode.

Creating these reports is done by customizing the ledger-reports variable. It's also possible to set them using the ledger-reports-add function, but I prefer to set them all in one go during setup.

My current list of reports looks like this:

(setq ledger-reports
 '(("bal"            "%(binary) -f %(ledger-file) bal")
   ("bal this month" "%(binary) -f %(ledger-file) bal -p %(month) -S amount")
   ("bal this year"  "%(binary) -f %(ledger-file) bal -p 'this year'")
   ("net worth"      "%(binary) -f %(ledger-file) bal Assets Liabilities")
   ("account"        "%(binary) -f %(ledger-file) reg %(account)")))

bal: Shows the balance of all accounts; this also includes individual expenses (such as Expense:Car:Gas) so it's a pretty long report.
bal this month: As above, but only includes transactions from the current month.
bal this year: Same as bal, but limited to the current year.
net worth: A short report that shows what I've got in each account, as well as what I owe on loans and credit cards.
account: This prompts for an account name and then shows its transactions for the current file. This is useful for quickly seeing how much money has been spent on a specific category during the year.

Emacs reports that have the %(ledger-file) token are run against the current ledger file. I have my Ledger files stored in a projectile project so I can quickly jump to them to run reports or make adjustments.

Managing RSS subscriptions with elfeed and Tiny Tiny RSS

Tue, 20 Jul 2021 19:50:00 -0400

I've been using elfeed as my primary RSS reader for a couple of years, but there were a few things I missed about my previous web-based reader. One annoyance was that items I read on my laptop weren't synced with whatever I read on my desktop. I also missed having an online view for when I was out of the office.

Fixing the second problem was easy: Tiny Tiny RSS is a web-based RSS reader that is free and open-source. I really like the interface, but I still wanted to read things in elfeed if possible. Thankfully there's a package called elfeed-protocols that allows elfeed to sync with tt-rss.

Configuring

Getting everything setup is fairly straightforward:

(use-package elfeed
  :defer t
  :init
  (elfeed-protocol-enable)
  :custom
  (elfeed-use-curl t)
  (elfeed-feeds    '(("ttrss+https://user@my.ttrss.com"
		      :password "<password goes here>"))))

The elfeed-protocol-enable part turns on additional protocol support, and elfeed-feeds tells elfeed which tt-rss server to use.

Tidying up the view

The default view takes up the full width of the window, which I find hard to read on a large monitor. I use the following addition to narrow things down:

(use-package elfeed
  ;; <- Regular config goes here.
  :config
  (add-hook 'elfeed-show-mode-hook #'sodaware/enhance-elfeed-readability))

(defun sodaware/enhance-elfeed-readability ()
  "Clean up elfeed show buffer."
  (setq shr-width 80)
  (buffer-face-set 'fixed-pitch))

elfeed uses Simple HTML Renderer (shr) to display articles, so this function limits the width and sets the font to a fixed-width one.

Marking items as read

Here’s a simple function that marks all RSS items as read before fetching new posts:

(defun sodaware/elfeed-all-read-refresh ()
  (interactive)
  (when (y-or-n-p "Really mark all items as read?")
    (elfeed-mark-all-as-read)
    (elfeed-search-fetch nil)))

MicroEMACS for the Atari ST

Mon, 24 May 2021 20:32:00 -0400

One of my goals this year is to create some software for the Atari ST. For my first project I wanted to use an environment that was close to the one I used growing up, but with improvements where possible.

The first thing I wanted to improve was text editing. The original BASIC editor I used lacks a lot of features I'm used to: it can only edit one file at a time, doesn't have copy/paste support, and navigating with a keyboard is quite limited.

A full-blown Emacs installation is a little large for the humble ST, but there is an alternative: MicroEMACS.

It doesn't have the full range of Emacs features, but it does have some handy functionality:

Supports multiple buffers.
Can mark regions and cut/yank them.
Has tab completion for commands and filenames.
Has much better keyboard support for moving around a buffer.
Can use C-s to search and .
Can record keyboard macros.

It doesn't do everything that modern Emacs does, but it's certainly an improvement on the editor I originally used.

MicroEMACS for the ST can be found on atariuptodate.de.

Distraction free writing with Emacs

Mon, 10 May 2021 20:37:00 -0400

I use Emacs for all of my writing (including this blog). For a long time I used the default environment, but I really missed the more focused approach of applications like WriteRoom. So a few years ago I made an effort to streamline my Emacs writing environment.

With a few additional modes - and a small amount of elisp - I was able to get Emacs looking like this:

(The theme is doom-nord and font is Ubuntu.)

It's a fairly simple setup with only a few different parts.

Removing distracting UI elements

I don't think a toolbar or menu is particularly distracting, but it's visual clutter that I don't use. This code comes from my minimal Emacs configuration and hides these elements:

;; Hide the menu bar, tool bar, and scroll bars.
(when (fboundp 'menu-bar-mode)   (menu-bar-mode   -1))
(when (fboundp 'tool-bar-mode)   (tool-bar-mode   -1))
(when (fboundp 'scroll-bar-mode) (scroll-bar-mode -1))

Centering and enlarging the text

The majority of my writing is done inside org-mode, but I also use org-mode to manage projects so I don't want every buffer to use these settings. For writing projects I use a .dir-locals.el file to automatically enable specific modes and to increase the font size.

((org-mode . ((eval . (progn (turn-off-auto-fill)
			     (text-scale-set 1)))
	      (fill-column              . 80)
	      (visual-fill-column-width . 80)
	      (olivetti-body-width      . 80)
	      (mode . olivetti)
	      (mode . visual-line)
	      (mode . visual-fill-column))))

The code in the eval block turns off hard-wrapping, increases the font size, and enables olivetti-mode.

I use olivetti to narrow the writing area to 80 characters which I find easier to work with. darkroom is a good alternative to olivetti; it provides similar functionality, but also more options and can even set an entirely different font face when enabled.

2021-08-11 edit - Updated .dir-locals.el with new activation as olivetti has removed the turn-on-olivetti-mode function.

~~~
If you found this helpful and would like to read more content like it, follow me on Twitter.

Automatically changing an org task's state when clocking time

Mon, 19 Apr 2021 20:02:00 -0400

In "how I get work done with Emacs and org-mode" I talked about how I manually switch a task to IN-PROGRESS when I start working on it. It's not a huge inconvenience, but I did wonder if I could configure Emacs to do it for me.

Of course there's a feature for that.

There are two variables that can be used to configure org's behaviour when clocking time:

org-clock-in-switch-to-state: The state to change a task to when clocking in.
org-clock-out-switch-to-state: The state to change to when clocking out.

Both of these variables can either be a string which will be the new state, or they can be a function. If they're a function it must accept ONE parameter - the task's current state - and return the state to switch to.

In practice it looks like this:

;; Always change the task to IN-PROGRESS.
(setq org-clock-in-switch-to-state "IN-PROGRESS")

;; Use a function to decide what to change the state to.
(setq org-clock-in-switch-to-state #'sodaware/switch-task-on-clock-start)

(defun sodaware/switch-task-on-clock-start (task-state)
  "Change a task to 'IN-PROGRESS' when TASK-STATE is 'TODO'."
  (if (string= task-state "TODO")
      "IN-PROGRESS"
      task-state))

It's a small change, but it smooths out a slight wrinkle in my workflow.

How I get work done with Emacs and org-mode

Thu, 15 Apr 2021 09:45:00 -0400

I've been a freelance developer for 12 years, and Emacs has been at the center of my working environment for 10 of those. I use it for a lot of things - including writing this post - but today I'm concentrating on my workflow.

Here's how I use Emacs and org-mode during a regular day.

The packages

There are two of packages that are central to my daily routine: org-mode and projectile.

org itself is a text markup language with a lot of extras that make it great for organizing work. org-mode allows Emacs to extract this information and use it for scheduling tasks, estimating task effort, tracking time, and a whole bunch of other things. I remember reading that org is a gateway drug that leads to Emacs - that was certainly the case for me.

projectile adds functions for navigating between projects and files. A project in the world of projectile is a file directory, which is usually a git working directory in my case. In a typical day I can work on a dozen different projects, so being able to quickly jump between them is extremely helpful.

I use a lot of other packages when doing actual work, but these two keep me organized and allow me to quickly get to where I need to be.

The setup

All of my org files live in "~/Documents/org/" and are synchronized between my desktop and laptop.

Each client has their own .org file with headlines for each project that I'm working on. I also have inbox.org which I use for capturing new tasks, and goals.org which contains my monthly goals.

Major personal projects also have their own org files, although I'm slowly transitioning to per-project "TODO.org" files instead.

All of these files are added to the org-agenda-files list so that they show up in my org agenda.

;; For Emacs versions < 25
(setq org-agenda-files
      (find-lisp-find-files "~/Documents/org" "\.org$"))

;; For version >= 25
(setq org-agenda-files
      (directory-files-recursively "~/Documents/org/" "\\.org$"))

Update: thank you to kaiwen1 on reddit for letting me know about directory-files-recursively.

The agenda

The org agenda is a powerful way to display tasks from across multiple files. Agendas can be filtered to a time period, urgency, project, and much more.

My daily agenda looks something like this ¹:

This view has 5 columns that display the following information:

Category - For freelance clients I use the client name, followed by the project. This looks something like client:project. Personal projects use just the project slug.
Estimate - I try to keep individual tasks on this list to under 2 hours. If it's longer than that, it probably means I haven't broken it down enough.
Scheduled date or deadline - When this is task is due or if I've scheduled it for a particular day.
Task name - This contains the task status, its priority, and its name.
Tag - This is used to identify project and client tasks, and also to store my monthly goals. I used to use this for GTD-style contexts, but seeing as 99% of my work is at the computer I didn't get much use from it.

The configuration for these columns is fairly simple:

(use-package org-agenda
  :after org
  :custom
  (org-agenda-prefix-format '((agenda . " %i %-20:c%?-12t%-6e% s")
			      (todo   . " %i %-20:c %-6e")
			      (tags   . " %i %-20:c")
			      (search . " %i %-20:c"))))

And the actual agenda configuration (without the code to display my monthly goals) looks like this:

(setq org-agenda-custom-commands
      '(("d" "Today's Tasks"
	 ((agenda "" ((org-agenda-span 1)
		      (org-agenda-overriding-header "Today's Tasks")))))))

To view my daily agenda, I'll run M-x org-agenda (which I have bound to C-c a) and then select d for the "Today's Tasks" view. It shows me everything I have scheduled for the day, as well as due and upcoming deadlines.

The day plan

At the start of the day I'll open my agenda and choose which tasks to work on, based on due date and priority. I'll then block out time to work on them on my paper day plan. I'll always leave some extra room for tasks that will pop up during the day.

The day planner itself is really simple and looks a bit like this (shortened to save space):

	Monday	Tuesday	Wednesday	Thursday	Friday
9-10	Task A
10-11	Task B
11-12	Task C
12-1	Lunch
1-2
2-3	Task C

I split my work day into blocks of one hour to make things easier; I've tried slots of 30 minutes long, but that felt less flexible and quickly fell apart if something came up. I use red for billable tasks, green for personal projects, and orange for essentials like exercise and eating.

Although org-agenda can be used to create day plans that are similar to this, I prefer having a paper copy in front of me. It lets me get a quick overview of how busy the day is going to be, as well as how much is going to be spent on billable time vs personal projects.

Adding new tasks

I generally deal with two kinds of task: proactive, and reactive.

Proactive tasks are things I've already planned out; I can choose when to work on them, and I know when they're due and what urgency level they are.

Reactive tasks are when emails/calls/chat messages come in and I need to do something about them. They may be urgent and need doing ASAP, or they may end up on the proactive list.

We'll start with reactive tasks first.

An example non-urgent request would be something like "We're wanting to add a new report to <product> by next month. Design and documentation attached"².

I'll open up the org file for this client, jump to the appropriate project node, and add a new sub-task for this request. In this example it would look a bit like this:

* TODO Create new "days without an accident" report [0/4]
  DEADLINE: <2021-04-30 Fri>
** TODO Email person re: new report
   SCHEDULED: <2021-04-15 Thu>
** TODO Create markup for new report
** TODO Add data backend to new report
** TODO Deploy new report to staging for tests

I'd also break down each sub-task into individual steps and add estimates, but that's a topic for another day.

Once this is done, the first task will show up on my daily agenda. My weekly agenda will also have a reminder that there's an upcoming deadline.

For scheduling proactive tasks I'll read through my list of tasks and assign dates as needed. org-agenda can search for top-level TODO items and filter them by category and context. It can also list "stuck" projects that don't have an assigned next action.

Working on a task

When it's time to work on a task, I'll use org's clock timer to track the time I spend on it. Starting work looks like this:

I highlight the task in the agenda.
Hit <enter> to jump to its entry in the appropriate file.
Switch the task to IN-PROGRESS.
Start clocking time with C-c C-x C-i.
Navigate to the project with C-c p p.
Choose the file I need to be working on and start.
Use C-c C-x C-o to stop the clock once I'm done or need to switch.

I know all the previous steps sound like a lot, but going from my agenda to working on a task only takes a few seconds.

Emacs also supports bookmarks, so if I want to start on something immediately the next day, I'll leave a bookmark in the right spot so I can jump straight to it.

Tasks in org have a keyword at the start to indicate their status. I use the following keywords:

TODO - A task that I need to do.
IN-PROGRESS - A task that I've started and is actively being worked on.
TESTING - A task that is being tested and reviewed by the client.
WAITING - A task where I'm waiting on something - could be more information about what needs doing, or it could need an external party to review it.
TO-DEPLOY - It's done and ready and waiting to deploy at a specific date & time.
DONE - It is done and nothing needs doing on it again.
CANCELLED - The task/project was cancelled for one reason or another.

Because org-agenda can search for keywords, it's easy for me to check for various tasks during my weekly review. For example, I can check through the WAITING list and see if I need to follow up on anything.

I also use org for detailed project planning; it's great for breaking down a task into chunks, adding estimates, and assigning to milestones. But this post is already ~~boring~~ long enough so I'll save that for another day.

~~~
If you found this helpful and would like to read more content like it, follow me on Twitter.

Footnotes:

I've been doing this job for 12 years but it's really hard to come up with imaginary tasks.

At least with made up examples they include all the info I need first time.

Moving text around in Emacs using move-text

Mon, 12 Apr 2021 19:52:00 -0400

move-text is a simple Emacs package that lets you move a line or region around using M + ↑ and M + ↓. It's not limited to plain text buffers - you can move lines of source code around too.

In practice it looks like this:

I prefer to use Control + Shift with the up and down arrow keys, so my configuration looks like this:

(use-package move-text
  :bind
  (("C-S-<up>"   . move-text-up)
   ("C-S-<down>" . move-text-down)))

Cutting and pasting a region is usually quicker, but for shuffling a few lines around this method is quick enough.

Configuring bug-reference mode from within org-mode

Mon, 29 Mar 2021 20:17:00 -0400

A few weeks ago I learnt about bug-reference-mode, a neat little Emacs minor-mode that automatically links text to a bug tracker. A few of my projects use bug trackers or GitHub issues, and different clients often have their own systems.

There are two variables that I usually want to set for bug-reference-mode:

bug-reference-url-format: The URL of an individual bug, with %s used as a placeholder for the bug ID.
bug-reference-bug-regexp: The regular expression that finds bug ID references. This is usually something like #1234.

I use directory local variables¹ for a lot of projects, but Emacs also supports file local variables for more fine-grained settings. org-mode has its own syntax for setting file local variables, so I needed to adjust things slightly to get it all working.

Setting local variables for a bug tracker looks like this:

# Local Variables:
# mode: org
# bug-reference-url-format: "https://example.org/tasks/%s"
# bug-reference-bug-regexp: "\\(#\\)\\([0-9]\\{8\\}\\)"
# End:

On my first attempt I skipped the Local Variables: and End: keywords, but they are needed for org to pick these variables up.

Footnotes:

These are variables that are set for all files in a directory and its sub-directories.