Adjusting HDMI volume on Catalina

Normally when you output audio through HDMI, you cannot control its volume from your Mac. You adjust it on the output device instead, whether it is a monitor or TV.

I’m working on my Catalina laptop while my mini is in the shop and using my newish DELL monitor without my normal speakers, which plug into the headphone jacks. With this setup, my music is loud, even when I have the monitor settings fairly low.

As it is a pain to adjust volume through the monitor menu, I decided to give Soundflower/SoundflowerBed a try. I was quite sure that Catalina would have killed it by now.

I was wrong.

In SoundflowerBed, I chose HDMI for the 2-channel output.

In System Preferences, I selected Soundflower (2ch) as my sound output device.

Boom. My volume control came back to life and my ears are recovering from the onslaught.

Seeing an old friend keep plugging along and doing what I need is remarkably satisfying. Thank you to everyone who has worked on Soundflower through the years, from Alexander Hudek and RogueAmoeba to MattIngalls and Maciej Wilczyński.

Circles within circles: custom types and extensions

So the other day Paul and I were shooting the breeze about spirographs. He was saying I needed to get back to blogging now that I have the time. Of course, the second you set out to try to write a post, so many ideas flow forth at once, it actually is hard to pick just one and focus on it. Since he had enjoyed my drawing work, I thought I’d start out with a little push at circles.

That quickly went out of control because I ended up with enough material for a few chapters rather than a single blog post. (And, no, my chapter for his book is about property wrappers, which I love, rather than drawing)

To give a little context, before I decided to try my hand at full time work, I had had a contract with Pragmatic to update my Drawing book. I had to cancel that because commuting full time to another city left me with zero free time for my self, my family, let alone writing. (Now that I am back at my own desk, I may see about returning to that project because geometry is a core passion.)

Anyway, let me start at the end of all this and show you some pictures and then I’ll (pardon me) circle back and start telling the story of the code and how all this came to pass.

I started my day by opening a playground, deciding to just flex my coding and see where it would take me. I wanted to work with circles, so I plugged a range into a map to get me there.

// Get some points around a circle
let points = (0 ..< nPoints).map({ idx -> CGPoint in
  let theta = CGFloat(idx) * (CGFloat.pi * 2 / CGFloat(nPoints))
  return CGPoint(x: r * cos(theta), y: r * sin(theta))
})

// Create a path
let path = UIBezierPath()

// Get the last point before the circle starts again
let lastIndex = points.index(before: points.endIndex)

// Draw something interesting
for (point, index) in zip(points, points.indices) {
  let p0 =  index == lastIndex
    ? points.startIndex
    : points.index(after: index)
  let p1 = index == points.startIndex
    ? lastIndex
    : points.index(before: index)
  path.move(to: .zero)
  path.addCurve(to: point, controlPoint1: points[p0], controlPoint2: points[p1])
  
}

It’s not the worst code in the world, but it’s not great. I was rewarded with a pretty path, so whee. Still, the code was screaming out that it wanted to be better.

I started by attacking the index work. Why not have an array that supported circular indexing by offering the next and previous items? So I built this:

public extension Array {
  /// Return the next element in a circular array
  subscript(progressing idx: Index) -> Element {
    idx == indices.index(before: indices.endIndex)
      ? self[indices.startIndex]
      : self[indices.index(after: idx)]
  }
  
  /// Return the previous element in a circular array
  subscript(regressing idx: Index) -> Element {
    idx == indices.startIndex
      ? self[indices.index(before: indices.endIndex)]
      : self[indices.index(before: idx)]
  }
}

Before you start yelling at me, I quickly realized that this was pretty pointless. Arrays use Int indexing and I had already written wrapping indices a billion times before. Just because I has the concept of a circle in my head didn’t mean that my array needed to. I pulled back and rewrote this to a variation of my wrap:

public extension Array {
  /// Return an offset element in a circular array
  subscript(offsetting idx: Index, by offset: Int) -> Element {
    return self[(((idx + offset) % count) + count) % count]
  }
}

Much shorter, a bit wordy, but you can offset in either direction for as far as you need to go. I did run into a few out of bounds errors before remembering that modulo can return negative values. I decided not to add in any assertions about whether idx was a valid index as arrays already trap on that, so a precondition or assertion was just overkill.

Next, I decided to design a PointCircle, a type made up of points in a circle. Although I initially assumed I’d want a struct, I soon realized that I preferred to be able to tweak a circle’s radius or center, so I moved it to a class instead:

/// A circle of points with a known center and radius
public class PointCircle {
  
  /// Points representing the circle
  public private(set) var points: [CGPoint] = []
  
  /// The number of points along the edge of the circle
  public var count: Int {
    didSet { setPoints() }
  }
  
  /// The circle radius
  public var radius: CGFloat {
    didSet { setPoints() }
  }
  
  /// The circle's center point
  public var center: CGPoint {
    didSet { setPoints() }
  }
  
  public init(count: Int, radius: CGFloat, center: CGPoint = .zero) {
    (self.count, self.radius, self.center) = (count, radius, center)
    setPoints()
  }

  /// Calculate the points based on the center, radius, and point count
  private func setPoints() {
    points = (0 ..< count).map({ idx -> CGPoint in
      let theta = CGFloat(idx) * (2 * CGFloat.pi / CGFloat(count))
      return CGPoint(x: center.x + radius * cos(theta), y: center.y + radius * sin(theta))
    })
  }
  
}

I added observers to each of the tweakable properties (the radius, point count, and center), so the circle points would update whenever these were changed. By the way, this is a great example of when not to use property wrappers. Wrappers establish behavioral declarations, which this is not. My circle uses the observers instead to maintain coherence of its internal state, not to modify, limit, or expand type side effects for any of these properties.

Now I could easily create a circle and play with its points:

let circle = PointCircle(count: 20, radius: 100)
let path = UIBezierPath()
for (point, index) in zip(circle.points, circle.points.indices) {
  path.move(to: circle.center)
  path.addCurve(to: point,
                controlPoint1: circle.points[offsetting: index, by: 1],
                controlPoint2: circle.points[offsetting: index, by: -1])
}

I decided not to add some kind of API for passing a 2-argument (point, index) closure to my circle instance. It doesn’t really add anything or make much sense to do that here. It wouldn’t produce much beyond a simple for-loop, and the point here is to build a Bezier path, not to “process” the circle points.

My goal was to build enough support to allow me to iterate through the points and reference adjacent (or further offset) points to build curves. This does the job quite nicely.

It didn’t feel quite finished though. I wanted to add a little extra because one of the things I often do with this kind of drawing is create stars and points and loops using offsets from the main radius, often interpolated between the main points on the circle’s edge. Because I had built such a simple class, adding an extension for this was a snap:

extension PointCircle {
  /// Returns an interpolated point after a given index.
  ///
  /// - Note: Cannot pass the existing radius as a default, which is why the greatest finite magnitude is used
  public func interpolatedPoint(after idx: Int, offsetBy offset: CGFloat = 0.5, radius r: CGFloat = .greatestFiniteMagnitude) -> CGPoint {
    let r = r == .greatestFiniteMagnitude ? self.radius : r
    let theta = (CGFloat(idx) + offset) * (2 * CGFloat.pi / CGFloat(count))
    return CGPoint(x: center.x + r * cos(theta), y: center.y + r * sin(theta))
  }
}

The most interesting thing about this is that you cannot use a type member to default a method argument, which is why I ended up defaulting it to `greatestFiniteMagnitude`. It seems to me that it would be a natural fit for the Swift language to allow that kind of defaulting. In this case, it would say: “If the caller doesn’t specify a radius, just use the one already defined by the instance.” What do you think? Is that too weird an ask?

To wrap up, here’s an example using the interpolation:

let path2 = UIBezierPath()
for (point, index) in zip(circle.points, circle.points.indices) {
  path2.move(to: point)
  path2.addCurve(to: circle.points[offsetting: index, by: 1],
                 controlPoint1: circle.interpolatedPoint(after: index, offsetBy: 0.33, radius: circle.radius * -2),
                 controlPoint2: circle.interpolatedPoint(after: index, offsetBy: 0.67, radius: circle.radius * -2))
}

All the shapes at the start of this post are created from this and the preceding loop by tweaking the curve parameters. What pretty results will you come up with? If you build something particularly lovely, please share. I’d love to see them!

Reading stdin on the fly

Shai Mishali asks, “Is there something like readLine that lets me read stdin as the user types instead of waiting for an entire line?” The readLine function waits until the user presses enter or otherwise recognizes EOF to process input.

A little web search led me to this SO post, which is  based on this example, using termios, the Unix API for terminal I/O. After looking through both posts, I built a RawMode type to support direct input based on that code because nothing makes me happier than messing with solutions to make them a little swiftier.

To use this, you fetch bytes until you catch an EOF. It’s interesting to test both direct keyboard entries as well as pasting complex emojis. As I was working on this on both 10.14 and 10.15, I was mildly startled when my initial test code stopped working when I moved to 10.14. UnicodeScalar does not offer a utf8 view until 10.15:

extension Unicode.Scalar {
  @available(macOS 10.15, iOS 13, tvOS 13, watchOS 6, *)
  @frozen
  public struct UTF8View {
    @inlinable
    internal init(value: Unicode.Scalar) {
      self.value = value
    }
    @usableFromInline
    internal var value: Unicode.Scalar
  }

  @available(macOS 10.15, iOS 13, tvOS 13, watchOS 6, *)
  @inlinable
  public var utf8: UTF8View { return UTF8View(value: self) }
}

So thank you, Swift team, for giving us that. It’s a nice addition to the language!

Anyway, if you have a different approach or you can see ways to improve my take further, drop a comment and let me know.

Black Cyber Friday Monday and the art of the outdated iPhone

I decided to replace my aging iPhone 6+ a few months ago with a refurbished one- or two-years old iPhone model. The iPhone XR seems like a solid choice and I looked forward to some Black Friday/Cyber Monday deals. I assumed I’d purchase a “renewed” model rather than pay full price from Apple.

Then reality hit.

The “renewed” unlocked 128GB XR went from about $560 a few weeks back to $600 on Black Friday and soared even higher over the weekend. Today, it’s back “down” to $630 although it exceeded that price at its height..

Apparently, secondary markets plus high consumer demand create different pricing outcomes than shiny loss leaders.

This lead me to a sea-change in my planning and expectations.

An unlocked brand new SIM-free 128GB XR retails for $649 from Apple plus they throw in a $50 gift card today. If I hand over my existing iPhone 6+, my price goes down $80 (although I’m tempted to hand it down to a child). Not having to deal with Gazelle or the vagaries of Amazon vendors seems like a happy outcome.

Oddly, this is the last major purchase from my yearly “Pick up on Black Friday/Cyber Monday” list. The rest all went fairly smoothly, especially the $129 Apple Watch 3 for my middle child (Thank you David Ashman!) and the $649 MBA for my eldest.

I find year-by-year my purchase requirements are shrinking and changing. I’m spending more on services like iCloud and Backblaze, VPNs and NoIP, and less on hardware. I didn’t bother buying any external backup hard drives this year as I still have a couple in boxes from last year.

For those keeping track, I didn’t replace or upgrade my 2012 Mac mini although I am seriously considering the dual drive upgrade several of you recommended. I now run Mojave and Catalina installs on separate machines because I don’t want to lose access to thousands of dollars of software from the 32-bitpocalypse while I need access to the latest dev tools and OS. It’s a fairly frustrating situation.

So where did I spend my BF/CM money? This year, it was mostly about  gifts (carbon fiber PLA filament for the boy, Switch games for the girls), education (the watch and the laptop), and prosaic things-we-simply-needed (replacing a broken space heater).

It was also a good lesson on what not to buy during the rush.

Review: In praise of Ring Fit Adventure

I bought my son Ring Fit Adventure as a reward for bringing home good grades. Little did I know that I would soon monopolize the game. Yes, he uses and loves it too, but only after school. For me, it is full of 2-10 minute exercise breaks perfect for pausing work and getting myself moving.

I recently left a position with a massive commute to a nearby city, ridiculous hours, and lots and lots of sitting. It completely broke up my routine, which had previously included a well considered mix of resistance, strength, flexibility, and aerobics (mixed with a bit of Restorative and Yin yoga, which are the bomb).

My fitness pre-job was hard earned. Lots of its early ramp-up was due to a mix of physical therapy and Wii Fit (or as I like to call it Wii Fiit). Despite the harsh criticism Wii Fit gets, it is an amazing tool for convalescence and several of its activities (most specifically boxing) can get a good heart rate and sweat going. I particularly love its quirky “yoga”, which opened me up to a much wider world of non-scare-quote yoga.

Wii Fit eventually evolved into Wii Fit Plus, which I have never played, mostly due to the fact that we own a bunch of Wii Fits and I never saw enough value to upgrade to the newer system. When the Switch debuted, I hoped they’d continue Nintendo’s fit tradition, and Nintendo finally delivered with Ring Fit Adventure. (Also, it tickles me silly that the Wii Fit trainers are now in Smash.)

Ring Fit Adventure is basically an interval training system based on jogging in place mixed with resistance training using a Pilates Ring and some minimal stretching. It doesn’t sound like much but it works brilliantly. If you regularly move a lot of iron around in your life, this isn’t going to do much for you but if you’re coming off six months of nearly complete inactivity and want to get back in shape to take advantage of more physicality, it’s perfect.

I find it’s never hard to build a sweat and get my heart moving for a good 20-60 minutes. In addition the game has incentivized many of my most hated activities (I’m looking at you, Mr. Squats) and turned them into something I am determined to conquer. Yes, being short means the travel of the thigh sensor may be occasionally tricky to detect (meaning deeper squats for me) but the pilates-style ring is deservedly the star of this show.

From what I can guess, it has some interior material that changes resistance as it bends to allow the system to detect interaction both pushing in and pulling out. There’s a larger-than-expected vocabulary of fitness activities you can incorporate using those two actions including overhead presses and pulls, forward and rear, and the star of the show, the engaged “ab-guard”, which when done correctly allows you to engage your gluts, abs, and shoulders, or basically all the things my PT regularly tells me to engage.

Technically this is a game and there’s some kind of irritating storyline about a picked-on pilates-ring and his steroid abuser ex, but you can ignore most of that and enjoy the beautiful tracks and vistas. There’s a bit of repetition from world to world and a “cheat” system that involves drinking lots of smoothies (because pure sugar is always what people trying to control insulin metabolisms want in their system, right?) but these, too, are minor issues.

Mostly, the game is great because it is, at least for me, hard and it ramps up its difficulty level to level. I’m savoring each “world” and I am in no hurry to finish.  Most recently, I spent time pushing and pulling blocks along a running track with my arms so I could run without falling into holes and by the end of the course, I felt it. For me, finding that physical edge and training to that point of exhaustion just before it’s too much is what makes a great workout.

No, the biggest issue is that we have the one Switch and occasionally my child wants to use his toy without his mom demanding 100% access through the day.

This isn’t a cheap hobby. A basic fully fitted Switch with dock will set you back $300. Add in a second pair of joycons, and that’s another $70-$80. The game alone is $80. And if you end up destroying the pilates ring (the “ring controller” or “ring con”) that’s $45 + shipping direct from Nintendo. (And if you do break that, chances are good you’ll have banged up a joycon as well.) Fortunately, our ring is doing well despite the abuse we have put it through. And we have, as yet, not flung any joycons across the room or into the TV.

Despite the price, most of the cost involves things we would have bought anyway or already own. They’re expensive but have proved to be a delight for the family.

As for Ring Fit Adventure, you shouldn’t have to wait for your report card to treat yourself or your kids to this. I suspect the adults will be playing it longer than the kids unless you treat some of its minigames as pass-and-play so you can enjoy it together.

I hope there will be follow-up fitness products but based on Wii Fit/Wii Fit Plus, Nintendo has a respectable heritage of a single, focused fitness title.

I’ve been waiting for great training and fitness innovation products that combines the Apple Watch and Apple TV but so far, nothing has grabbed me in the way that Wii Fit and Ring Fit Adventure have.

What about you? Any amazing finds?

Taking charge of those xips

Apple adopted the digitally-signed xip format for Xcode downloads a few years ago. It’s basically a signed version of zip archives. Most commonly, you download a xip and double-click. Archive Utility will open the file, verify its signature, and expand its contents.

In its default settings, Archive Utility always expands files to the same folder you download to. With Xcode, this is a big pain as moving the app with its thousands and thousands of tiny subfiles and embedded executables takes forever. Alternatively, moving the xip file from one location on your system to another can be painfully slow.

Fortunately, Archive Utility does allow you to specify where to unpack. Launch the Application using spotlight (or /System/Library/CoreServices/Applications/Archive Utility.app) and open preferences.

Although there’s no “Ask” option for “Save expanded files”, you can select where you want items to be stored using “into” from the pop-up:

Once set, you have to unset it for general use, because the location persists between launches. This is, needless to say, a big pain when you use archives for non-Xcode purposes on a regular basis:

Fortunately, you can unxip more effectively by using the command-line xip utility located in /usr/bin/xip without having to mess with Archive Utility or its preferences:

% xip
Usage: xip [options] --sign <identity> <input-file> [ <input-file> ... ] <output-xip-file>

Usage: xip --expand <input-file>

99.9% of everything you do with xip is that last “Usage” example. Still, as xip doesn’t offer a --help option, if you want to know what those interesting [options] are, you’ll need to read the man page (man xip). I prefer to open man pages in Preview instead of the command line, using this little trick:

man -t xip | open -f -a /System/Applications/Preview.app

Notice two things here:

  • First, the -t flag tells man to use the Groff typesetter (no relation) to format the page to postscript. This presents as a PDF in Preview. (Specifically, it uses /usr/bin/groff -Tps -mandoc -c if that kind of detail intrigues you.)
  • Second, the path for Preview has changed in Catalina to /System/Applications. If you want to do this on Mojave or earlier, adjust the path accordingly.

(Isn’t that a neat way to view man pages?)

While the man page suggests you can sign your own xip archives and provide your own identities, don’t bother. This format is exclusive to Apple, starting  from macOS Sierra. Only xip archives signed by Apple can be expanded in modern macOS releases. (See Tech note TN 2206 for details.)

Since --expand cannot be used with any other arguments, hop over to /Applications, and expand from there:

% cd /Applications/
% time xip --expand /Volumes/Kiku/xips/Xcode_11.2.1.xip 

Adding the time command at the start of the line lets you know how long it took to unxip, which is deeply satisfying to those of pedantic bent like myself. For those playing along, it was

xip: expanded items from "/Volumes/Kiku/xips/Xcode_11.2.1.xip"
1109.625u 275.408s 10:58.85 210.2%	0+0k 0+0io 167pf+0w

Update:

Whisky tango foxtrot: Xcode allows ObjC switch unindenting

This happened.

You might think I’m about to go off on some Swift rant (and trust me there is a Swift rant inside me waiting to emerge) but it’s the second checkbox that made my mind explode.

From:

To:

Who thought this was a good idea? I’ve never been a fan of left-aligned case in Swift although I embrace it as the standard. But in Objective-Freaking-C? As a standard Apple-blessed toggle in Xcode? No! Thrice no! The option enabling the choice is bad for Swift and worse for Objective-C.

Why is this option in there and why is it available for both languages? It would be best to, as Joe Groff put it, “let sloth naturally lead everyone to pick the default” given that the feature has been expressed in Xcode. Or better yet, file some bug reports for the broken feature.

Each language default reflects years (and decades) of language style consensus:

  • Swift: keyword-aligned.
  • Objective-C: “scope”-aligned.

This new choice in preferences is madness.

Talk me down from here, friends.

Apple Pencil: Too much information

I own a first generation refurbished Apple Pencil. I bought it when I picked up the new 5th gen iPad mini. It’s a delight. I use it for freehand note-taking when I don’t want to tip-tap into the onscreen keyboard or lug around my folding bluetooth keyboard. I use it doodle and draw. I use it to annotate PDFs. I especially love  how it knows what is the pencil and what is my hand so I can rest against the screen and still get work done.

My pencil keeps its charge for days with light use. When I need to top it up, I can stick it into my iPad’s lightning port. In under 10 minutes it goes from flatline to 100% charge. Yes, it looks a bit odd sticking out like that, but it isn’t for long and it’s easy enough to rest the iPad on a desk until the charge is complete.

Keep track of your current pencil charge in your iPad widget gallery. The Batteries  section shows how much juice is currently available:

When talking about charging, you should think about that tiny cap at the end of the first generation pencil. Fortunately, there are many extremely useful and inexpensive helpers for keeping track of the cap and the charging adapter, the short flat item at the bottom of this picture. It’s used for charging off a USB lightning cable by providing a female-to-female connector between the cable and the pencil:

Many third party gizmos service these tiny pieces. You can purchase replacement magnetic caps that better stick to your pencil and replacement charging adapters for when you lose them. If you’d rather not lose them in the first place, consider a simple holder set like this one. Mine is clear silicon and did not include the tip that covers the nib. The holders make sure the two tiny pieces aren’t easily lost, and that they’re kept along-side the equipment that uses them:

In addition, I purchased a magnetic sleeve to attach my pencil to my iPad and/or its smart cover when not in use. Again, this helps ensure I don’t lose the things I need. I roll the flat part away from my hand and find that it doesn’t interfere with holding the pencil or writing with it.

I use the Selvy PenScript keyboard plug-in to convert handwriting to text. It’s available from my normal keyboard. I tap-and-hold the globe to select it. Make sure when installing that you enable it in Settings > General > Keyboards.

As you see from this screenshot, I also installed the Kaomoji.HW keyboard that allows me to draw emoticons. It’s not very good at its job but it’s pretty hilarious to play with.

The SelvyPen keyboard is surprisingly useful across apps. It’s as easy to enter a URL as it is to type free text.

If you’re looking to enter large tracts of text by hand, Nebo does a great job with handwriting-to-text conversion, allowing you to enter information into notebooks using your pencil. Notice how the app keeps track of the ongoing interpretation in light gray just above the handwriting:

Use the ellipsis (3-dot) menu on the right to convert paragraphs to text and remove the handwriting entry. The accuracy is surprisingly good.

For annotating PDFs, I use Notability. I admit that it’s mostly because I already own it and it’s a great app. There are many other excellent options on the market. I’d love to hear what else you recommend. I apologize for all the blurring but I was reviewing someone else’s work and I wanted to respect their privacy:

For presentation, I have a half dozen apps of varying quality and I can’t really recommend one or the other as being particularly outstanding:

What other apps, tweaks, and gadgets have you found to enhance your pencil-using experience? I love my pencil and am always looking for more ways to get the most from it!

Reader recs:

  • Many readers agree with my use of Notability
  • Mike recs Concepts. “I use it as a vectorized infinite whiteboard for sketching and note taking.”
  • Teddy likes GoodNotes, “which will hide the UI when projecting to an external screen. Also has a nice laser pointer with a trail so you can make temporary markings as you go” and PDF Viewer for annotation.
  • Paper by WeTransfer gets a thumbs up from Paul.

The knee-jerk else-clause

I’ve gotten into several heated discussions recently (I wouldn’t call them arguments or fights as no blows were exchanged and we departed as friends) about whether an if-statement should always include a balancing else clause in languages where it is not mandated by a ternary if form.

My feeling is a firm “no”.

Let me attempt to represent the opposing viewpoint. As far as I can tell, the “yes” faction believes that as proper diligence, an else clause should always be added to address both truth scenarios, even if the clause is populated with nothing other than a comment saying “this clause intentionally left blank”. It promotes a consistent inspection of all possible cases, on par with a switch statement requiring full coverage.

I firmly disagree. In my opinion, if-statements boil down to three scenarios:

  • Special CasingAction that applies solely to certain logic conditions, where the absence of those conditions has no effect in the logic. In such case, I recommend to skip the else. There’s no point to it as the flow of execution continues past the additional steps introduced by the if-statement. Adding an else statement removes the clarity of the step-by-step logic and reduces the weight of the special casing in understanding the code.
  • Either-Or: Separate actions of approximately equal weight that apply to both outcomes. If statements are naturally biased towards the positive clause. If both statements are weighted the same, consider refactoring to switch. Even if the switch is ordered (as it must be in some fasion), a switch-statement reduces the emphasis given to either outcome. If both cases are quite large, consider breaking out functionality to dedicated methods. Further, if the logic overlaps between both cases, consider localizing the conditions closer to the differences, even if the test may be applied several times.
  • One case complex, one case simple: Actions that are of disparate impact or weight, where one clause greatly exceeds the complexity of the other, I always place the more complex clause first when used in an if-statement to emphasize the positive path. At the same time, if the simple case is non-trivial, this is an opportunity to consider whether the logic should be broken up or refactored in some way. If an if-clause is so significantly big that it takes up the majority of a method implementation, perhaps you should be using early return for the lighter condition and promoting the more complex logic to the main method body. To me, a heavy complex if-clause usually signifies an opportunity to refactor.

Given these styles, I don’t see any reason, whether from code-reading clarity or a strict adherence to potential future expansion, to automatically include else-clauses as a mandatory part of a coding style. They add heaviness without real functionality and speak to a philosophy of form weighed over functionality. Code should be light, clear, and direct. Mandatory-else is none of those things.

Am I wrong? Go ahead, convince me otherwise. I’m listening.

Lightweight To-Do list formatting

I recently ran across the todo.txt format project, which allows use to use plain text action item lists to create and manage your projects. I love the simplicity of the idea but there were a number of items that prevented me from wholeheartedly adopting it.

First, I think it’s really ugly. It’s hard to scan, especially when there are lots of things to do. I know that the idea is this is an intermediate representation but that representation is visually heavy.

Second, it’s missing notes. Freehand notes are an important part of task management, whether noting down the phone number for the car place when you need to get your snow tires put on.

Third, it’s order dependent, with a left-to-right layout that really doesn’t work for me.

Fourth, I don’t think the (A)-(Z) priority format is particularly readable.

Even though I do like the +Project and @Context annotation, I feel like todo.txt is a few steps  short of a much more flexible and readable intermediate form.

So I started brainstorming on how I might tweak this concept to be more flexible. For one thing, I think the example strains to make the project and context “fluent” in a way that they don’t have to be. Yes, you may want to query to see “what are all the projects I am working on?” and “what contexts do I work in?” so I can support differentiating them but I don’t think they need to be integrated into the to-do text.

What follows is a very lightly-considered redesign that I have pulled entirely out of thin air. I did not spend much time on this and I’m sure there are better ways to redesign this to support text-based lightly annotated human-readable to-do lists. I’m throwing this out there as a starting point in case any of you want to carry this discussion further. It’s a design exercise for me, one that allowed me to take some of these thoughts out of my head and throw them into a blog post. So take this for what it is.

Imagine tagging that looks like more like this, depending on whether you’re annotating project or context values. Part of me pushes back at the notion of the two types of tagging but I appreciate that you might want to query “show me all my projects” and “show me all my contexts”, and I recognize the value in that:

@(tag) or +(tag)
@(key: value) or +(key: value)
@(priority) or +(priority)

A priority can be as simple as a number, which I think people would process better than “A”, “B”, “C”, etc. As a pattern of (0-9)+, it would also allow easy differentiation in parsing between a tag (arbitrary text) and a priority. Priorities would range from 0 (highest priority) to any arbitrary number (lower priority). I doubt people would use more than two or three priority levels (low, medium, high), if they use them at all.

Because dates are critical for todo deadlines, you could pull them out with NLP or be more explicit: @date(due: 2019-05-02). The single keyword would allow you to parse a date with more flexible keys and disallow an explosion of keywords you might encounter by trying to pre-design specific scenarios like @due(2019-05-02), @checkin(next Tuesday), etc.

Relative dates would need a creation date, which if you’re using an editor rather than the raw format could be injected as @date(created: 2019-05-02). The second you do that, though, you’re moving away from the idea of human-readable, simple annotation, tool-consumable.

In my head, a better system would not be single-line. Adding blank spaces between items significantly increases vertical space so python-inspired indentation can avoid that:

Set up appointment for snow tires
  Call and talk to Judy 505-555-1212 # comments are always great
  She says to contact them at least one thursday before the weekend you want # Not thrilled by the manual line breaks here
  to bring the car in.
  @(home) +(winterizing) +(2) @(before: 2019-12-01)
Put snow scraper in car
  @(car) +(winterizing) @(done) # yay me!
Get flu shots for Bob and Francis
  Already got them for Fred and Mary
  @(family) +(health) +(season) +(Costco) +(1) +(shopping) # It's a shopping run, even if it's not strictly buying something

This is rough, obviously, but I think it’s a bit more readable than blockiness of the current format and a bit more flexible:

If working with an editor tool, I’d prefer if done items were automatically moved down to the bottom or maybe removed entirely or added to a different “done.txt” list.

Also, once you have the power of full tagging and categorization, a well built tool should allow you to pull on each of those to view related items in more structured ways. The format is simple but the way you present tagged information doesn’t have to be.

Anyway, those are my thoughts. I see a project with good bones that misses out on a bunch of human factors. What kind of changes would you make to turn this into a more usable and universal approach? Or would you just say “plain text is not really appropriate here” and use OmniFocus or Things instead? I’m curious as to what you think.

Update: Readers mention: