macOS installer cards


2016-09-29 20:16:20 UTC

Being both a creature of habit and a digital packrat, I never install macOS from the “Install macOS” app.

Instead, what I do is have a cache of 8 GB class-10 microSDHC cards (usually bought from Micro Center, but they make great Amazon filler items, too), which I permanently assign as macOS installer media.

(I would buy SDHC cards, but Micro Center sells the microSDHC cards for cheaper—50¢ cheaper as I write this.)

Populating the card

Once you have a card, you’ll need to put the bits on it. DiskMaker X is the easiest way to do this, though there is also a manual process.

Labeling it

Anonymous cards all of the same capacity and speed and possibly even description does not scale well as an inventory system. Ideally, your card comes in a clamshell case, like the Micro Center ones do, or you can reassign such a case that came with another card. You can probably even buy empty microSD cases, like you can CD jewel-cases.

I have a Brother labeler that I use to print a small label with the release’s version and marketing name on it: “OS X 10.7 Lion”, “OS X 10.8 Mountain Lion”, “OS X 10.9 Mavericks”, “OS X 10.10 Yosemite”, “OS X 10.11 El Capitan”, and now “macOS 10.12 Sierra”. That label goes on the front of the case.

Photo of my flash memory cards on which I have the past several years' macOS installers. Lion was on an SD rather than microSD card; Micro Center have changed their case form factor a few times; I started printing rather than hand-writing labels with 10.9, and I haven't yet labeled the card that will go to Sierra.
I wrote this while the Sierra installer application was downloading.

And then done

The very pretty installation volume that DiskMaker X created for Sierra, complete with window background matching the installer icon.

Now you have labeled, permanent installer media that you can use forever (or however long the cards last). If you ever need to roll back to an old version, reinstall the dot-zero from the card and then combo-update up to whatever version you want.



2016-09-12 21:48:59 UTC

I just got this ad for Jane Kim, who’s running for State Senate here in California:

“JOIN US as we work to lift more families into the middle class through better public education”! and “Median Annual Wage for City College Graduates: $59,800. Median Annual Wage for High School Graduates: $48,700”

Leaving aside the matters of whether those are livable wages in the City, particularly after taxes and any available savings contributions, and especially for “families” as stated in the headline…

“Join us as we work to lift more families into the middle class…”

A “middle class” necessarily implies a lower class and a higher class.

Right off the bat, this proposition does not even consider lifting families into the upper class. Just the middle class—that’ll do for now, right?

Lifting “more families into the middle class” implies not eliminating the middle class—there’ll still be one, which means there’ll still be a lower class, which means there’ll still be people/families in it.

Certainly this proposition does not suggest ending classes altogether—no; there’ll still be classes, at least three of them. And some will be in the upper class and some will be in the lower class and hopefully more of the latter will move up… to the middle.

Oh, OK.

I feel like this is a lukewarm dish. That’s all you’ve got to offer? You want to make this not only a headline on your flyer, but literally the entire topic of an entire flyer?

I’m not even saying it’s a bad idea. Just… it lacks ambition. It feels resigned. This is the best we can do, it implies.


NB: I feel I should make explicit that I’m not against Kim necessarily; I haven’t looked at any other candidates. And maybe she’s got lots of good policies and/or ideas. Just, this one ad caught my eye and got under my skin.

So you want to run an open-source project


2016-09-11 14:12:30 UTC

How much of this you’ll want to do will depend on just how much of a Thing you want your project to be, on a scale from “I’m just gonna drop some code on GitHub” to “I want to wear the title of ‘maintainer’”.


You don’t have to use GitHub as such; Gitlab and Bitbucket are alternatives, and they’re all more or less equivalent. But GitHub has network effects in its favor: Most potential contributors are there.

“Contributors” doesn’t just mean code. Anybody can clone your repository, check something in, and email you the patch. But writing issue tickets and editing the wiki (if you choose to have one) are valuable, too, and those typically require an account.

Your project on GitHub (or wherever) will include one or more of the following:

  • Code/contents (the Git repository from which GitHub and Gitlab take their names)
  • An issue tracker (more on that later)
  • Forks (other people’s copies of your repository, to which they have their own access to push changes)
  • Merge requests (changes made in one fork, then submitted “upstream” toward the original repository for consideration and possible integration into the “main” code base)
  • A wiki (documentation)
  • A website


Like with GitHub, there are alternatives. Travis is the one I’ve used.

Travis is a continuous-integration system. Whenever someone pushes changes to your repository, or submits a merge request, Travis will build your project and run your tests, according to instructions you provide. It’ll then provide an indication—on GitHub, right on the merge request page—of how well or poorly that went.

There’s a related service called Coveralls that tracks the code coverage in your project—how much of your code is being run by your tests. Code paths that the tests aren’t going through are potential bug sites: When that code path does get traveled, what happens might not be what you expect.

Coveralls tells you how much of your code was exercised, as a percentage, and also gives you a line-by-line map of what code was run and what code wasn’t.

Project infrastructure documents: README, LICENSE, CONTRIBUTING/CODE_OF_CONDUCT

(If you write these in Markdown, they’ll have the .md extension:, etc.)


Your README is your Getting Started guide for both users and contributors. Awesome Labs has a template you can follow (optimized for iOS libraries); the basic points you should cover include:

  • What is the product? What does it do? Why do I need it?
  • What does it look like? (Screenshots/example terminal sessions/example code)
  • What does it require?
  • How do I install it?
  • How do I use it, at least in the most common case?
  • How do I uninstall it (if applicable)?


This is where you put your statement of copyright, and the license agreement for your program, outlining what sorts of copying you explicitly allow and which ones you explicitly don’t. Common ones include variants of the BSD and MIT licenses, GPLv2, and GPLv3.

GitHub suggests a few popular licenses when you create a new repository, and provides an advanced section with many more licenses where you can compare their finer points.


This file describes guidelines for contributors, including:

  • Requirements of the contributions themselves. Examples of such requirements include:
    • Please add tests for any new features, and update tests for any behavior changes.
    • Please run the tests and be sure they pass before submitting your merge request.
    • Your change must pass all tests on all supported platforms. See the README for our platform requirements.
    • Please match the style of existing code. In particular, please use one tab/four spaces/eight spaces/6.34 spaces per indent, and please put opening braces ({) on the same line/their own line.
    • Please submit the complete, original series of changes—don’t squash merge.
    • Please squash-merge your changes—we don’t want the complete, original series of changes.
  • Information on how to contribute, if it differs at all from the usual “fork the project, commit and push your change, then submit a merge request”.
  • Requirements of contributors (e.g., a code of conduct such as the Contributor Covenant).
  • Info about any project mailing lists, IRC channels, Slack channels, etc., perhaps with their own code of conduct, such as the Community Covenant.

Codes of conduct are important for making explicit the standards of behavior you expect from project members and contributors. Don’t tolerate jerks—if somebody breaks your rules, even if their contributions are good on technical merit, kick them out. (You define what “kick them out” means, and may want to document it in your CONTRIBUTING file.)

Known jerks continuing to be tolerated/welcomed in your project is a visible “stay away” sign to other people who might otherwise bring equally good contributions with less hassle.

Issue tracker

Issue trackers are two things:

Your project management tool

You use issue tickets to track the work that has been done and that needs doing.

Most issue trackers provide a category/tag/label feature to identify on each ticket what sort of work it is. You can also create labels for priorities, if you want to track how essential or postponable each item is. (Some issue trackers have a separate priority field.)

Have a “help wanted” or “up for grabs” tag you can put on bugs that you don’t want to do yourself, and mention it in your CONTRIBUTING instructions. “help wanted” bugs are the ones you explicitly reserve for new contributors to do. Most should be simple or good introductions to the codebase, but you can also include harder jobs where (for reasons of your own time) you’re willing to accept the patch but not write it yourself.

You may also be able to create milestones for future releases you’re planning, into which you put each ticket to track when that work should be done (or at least landed), and, inversely, what work must be done before a release can ship.

Everyone else’s wish list

You’ll get a lot of bug reports and feature requests. Many of them will be duplicates, which you’ll close with a reference to the original/anointed ticket for the same bug/request/task.

If your project grows large/popular enough, you may choose to lock down the issue tracker so only contributors can add or edit tickets, and then take requests and bug reports instead through a support email address or form. Whoever reads that email then updates tickets as needed and sends ticket links or ticket numbers to support querents.

You will need to say no to some things, and some people will be displeased. You will also need to postpone some things because they aren’t as important or there isn’t a clear path forward (e.g., no steps to reproduce), and some people will be displeased because they want their feature/a fix now. There are no two ways about it; you are going to make some people unhappy. It’s not your fault.

Be polite; be fair; be the better person. Sometimes that still won’t be enough—some people won’t accept anything less than “yes, right away, it’ll be fixed in the next ten minutes”. And that sucks. But it’s not your fault.

Code review

Code review is where one or more contributors (and/or the maintainer) look at a proposed (or even already committed) change, looking for errors and potential improvements.

Some guidelines:

  • Review the patch, not the person. Don’t call the contributor an idiot or accuse them of wasting their time. Be gentle; be constructive. Yes, even if the patch is total trash—make it a teachable moment. Recognize language barriers and early learners. (But also don’t waste your time excessively—sometimes you will have to give up on someone who is a time sink. Even then, be nice.)
  • Prefer questions to statements. Be open-minded, not reactionary. Be willing to accept that an approach that isn’t what you would have done may be better. At the very least, be willing to accept it if it isn’t worse.
  • Praise good ideas, novel (but not overly clever) approaches, attention to performance, reliability, and ease-of-use, and hard work. Code review isn’t just a place to point out what they did wrong—it’s also a place to appreciate, explicitly, what they did right.

The simplest form is to look at the diff (the proposed change) in each merge request. You can comment on the merge request as a whole, and, on most services, on individual lines within the diff. Use these comments to ask for clarification, ask for documentation/comments, suggest changes, or suggest alternative approaches.

There are dedicated code review tools, such as Phabricator and ReviewBoard. I’ve used Phabricator; it’s good. I haven’t used ReviewBoard.

On a GitHub project, I typically just use the built-in merge request interface.

Package managers

They are many, and which ones you have to choose from will depend on what you’re making. For libraries for Apple platforms, there are CocoaPods and Carthage. For tools for macOS, there are Homebrew, MacPorts, and Fink.

Your README should include information on which package managers you support, and how to obtain your software through them. Expect people to request that you add your software on other package managers, or somebody to add it themselves and other people to subsequently complain to you when it doesn’t work. You decide what you do when these happen.


It should start with your README, but ideally should not end there.

If you’re making a library, have header/API documentation. On Apple platforms, Xcode now has built-in support for this; it’ll display the contents of your documentation comments when you option-click a symbol in C, Objective-C, or Swift code.

Another place to put documentation (and also do broader planning than fits comfortably in an issue ticket) is your project’s wiki.

Here’s how diskutil list describes a CD-ROM I bought at the Big Book Sale in Fort Mason:

/dev/disk14 (external, physical):
   #:                       TYPE NAME                    SIZE       IDENTIFIER
   0:        CD_partition_scheme                        *97.5 MB    disk14
   1:     Apple_partition_scheme                         84.9 MB    disk14s1
   2:        Apple_partition_map                         1.5 KB     disk14s1s1
   3:                        ISO                         46.1 KB    disk14s1s2
   4:                  Apple_HFS Operation Neptune CD    84.5 MB    disk14s1s3

This is an ISO 9660 “hybrid” disc. It presents a Mac volume when mounted on a Mac and a DOS/Windows volume when mounted on a DOS or Windows machine.

The HFS volume here is a fiction; the real ISO 9660 volume (despite its name of “Apple_partition_scheme”) is disk14s1—the first partition.

If you copy this partition, with something like:

sudo cp /dev/disk14s1 Operation_Neptune.iso

You will then have an accurate ISO 9660 disk image that you can mount on your Mac, and thus see the Mac contents, or on your DOS or Windows machine, and see those contents.

man() {
    env \
        LESS_TERMCAP_mb=$(printf "\e[1;31m") \
        LESS_TERMCAP_md=$(printf "\e[1;31m") \
        LESS_TERMCAP_me=$(printf "\e[0m") \
        LESS_TERMCAP_se=$(printf "\e[0m") \
        LESS_TERMCAP_so=$(printf "\e[1;44;33m") \
        LESS_TERMCAP_ue=$(printf "\e[0m") \
        LESS_TERMCAP_us=$(printf "\e[1;32m") \
            man "$@"

Screenshot of Terminal showing the zsh manpage with the above customizations.

Pretty neat, right? Let’s tear it apart, see what it’s doing, and think about how we might customize it to suit ourselves.

Read the rest of this entry »

Back again


2016-08-06 14:48:02 UTC

Sorry for the long period of downtime. It was caused by two things:

  • My previous host, Kaizen Garden, apparently went poof with no warning. (That was why the whole website was down for awhile.)
  • I got most of the site back up on its new home,, but got frustrated when I tried to restore the blog, so I just left it renamed out of sight until I next felt like making a run at it.

That was today. I finally sat down and got it all working, and fully upgraded WordPress while I was at it. The blog is back, everyone! Yay!

You will see some missing images. Apparently the backups I had only covered the WordPress database, not anything I’d uploaded as an attachment—those I only have through 2008. Oops.

Some of them I’ll be able to reconstruct. Fortunately I had good alt text on at least some of them, so I should be able to figure out what was there, and you should be able to make do in the meantime. And some of the images are definitely higher priority than others—the trigonometry figures, for example, will be among the first to come back.

So, please bear with me—the long recovery of this blog isn’t quite done yet. But this is progress.

Unicode date formats, YYYY?!


2015-10-24 08:41:08 UTC

Last year, I tweeted:

This year, I noticed that the problem comes earlier, so I sent out an early reminder:

But exactly what problem am I referring to? Dan Wood wondered exactly what the YYYY issue is and what languages it affects.

So here’s a short explainer, not bound by the constraints of Twitter.

Year for week-of-year

You may have heard of “ISO 8601 format” (2015-01-01), but in fact, that’s only one of three formats that ISO 8601 defines:

  • Calendar format: 2015-01-01
  • Week format: 2015-W01-04
  • Ordinal format: 2015-001

The ordinal format is straightforward: It’s the NNNth day of the calendar year.

But the week format does not work that way. The first week of a year is not even guaranteed to contain January 1st! Rather, -W01-01 (the first day of the first week) is the Monday of the week that contains the year’s first Thursday. (Yes, that is the actual definition from the ISO 8601 standard.)

As such, ISO defines a parallel track of years that have the same year numbers as calendar years, but start and end on different dates (and always start on a Monday). ISO-week-year 2015 starts on the Monday of the week containing 2015’s first Thursday; that Monday is Monday, 2014-12-29 (2015-W01-01). 2015-01-01 is Thursday, 2015-W01-04.

Unicode date formats

YYYY and yyyy are Unicode date format patterns. These offer quite a bit more flexibility than the old str[fp]time(3) formats, particularly in choosing different representations of the same value (e.g., “September” vs “Sep” vs “09” vs “9”).

  • YYYY is defined as the “year for week-of-year”: that is, the year for ISO week dates.
  • yyyy is defined as the calendar year.

Whom this affects

The second part of Dan Wood’s question is what languages this affects.

NSDateFormatter* and CFDateFormatter both accept the Unicode date format syntax.

Contrary to what I’d previously assumed, PHP does not use Unicode date formats. As befits PHP, it uses something that looks the same but works subtly differently: “Y” is always the full calendar year, whereas “y” is a two-digit calendar year. ISO week years are “o”.

I actually don’t know of any others. Feel free to chime in in the comments if you know any other languages or frameworks that include built-in support for Unicode date formats.

* On the Mac, an NSDateFormatter configured for “10.0 behavior” accepts str[fp]time(3) formats; “10.4 behavior” is Unicode date formats. All other current Apple OSs, including iOS, have NSDateFormatters with 10.4 behavior only. CFDateFormatter has never supported str[fp]time(3) formats.

Inspired by my own apartment hunt last year.

In no particular order:

  • Cell reception
  • Hot water
  • Outlets: Are they grounded? Are they ALL grounded? Are they REALLY grounded?
  • Proximity to laundry (in-building? coin-op laundry nearby?)
  • How good said laundry is
  • How expensive said laundry is
  • Window directions (east-facing: warm mornings; west-facing: warm evenings)
  • Can windows be opened?
  • Can windows be blinded?
  • Trash/recycling/compost disposal: Where? How? Capacity/limits?
  • Noise
  • Access to cable TV/internet
  • Access to transit
  • Does the building have a twin? (If so, you have a random chance of a resident of that building entering the wrong building and trying to get into what they think is their apartment.)

Alternatives to “guys”


2015-06-19 05:30:36 UTC

When you’re addressing a mixed-gender or unknown-gender group, you should not use the word “guys”.

(Everything in this post also applies to “dudes” and “fellows”, and the singulars of all three. For example, “the IT guy”.)

The word refers to people who are male. It doesn’t matter what you meant by it in a particular instance, or how you as an individual tend to use it: That is what it means. That is what it conveys. That is what people hear when you say it.

As Julia Evans found, different usages vary in how they’re received, and there’s almost always a difference by gender. You’re more likely to think “guys” is gender-neutral if you’re a guy.

When you use it to address people of mixed or unknown gender, you reinforce the idea of male-as-default: This masculine word can refer to anybody! Funny how that doesn’t work for feminine words.

When you use it to address people of mixed or unknown gender, you erase the non-male people in the audience: Everybody here is guys! There’s nobody else here, no non-guys at all, no, sir.

So stop it. Stop saying “guys”.

(Except, of course, when you really do mean a group entirely of guys, like a men’s sport team.)

You may think it’s perfectly normal. It’s common, and that’s different. “Normal” implies healthy, and this isn’t healthy.

If you start paying attention, it won’t sound so “normal” after all, once you start noticing every time somebody refers to people who aren’t all guys as guys.

You might think “OK, I’ll say ‘guys and girls’ or ‘ladies and gentlemen’ instead.” Don’t do that. That does not include everybody: There are more than two genders, and not everybody inhabits any of them.

We can do better than that. We can include everybody.

So, what should you say instead?

These are words and phrases that include rather than exclude. That acknowledge rather than erase.

If you have other alternatives to suggest, please do suggest them in the comments.

My 3D printing setup


2015-01-10 12:03:29 UTC

Here’s what I have today:


Photo of my 3D printer (1), with a glass plate (2) and small piece of blue painter's tape (3) on the print bed, an SD card (4) in its slot, a USB fan (5) outside, a USB strip light (6) inside, and a cuticle nipper (7) outside.

  1. The 3D printer is a PowerSpec 3D Pro from Micro Center. I believe it’s a rebrand of the FlashForge Creator Pro. For $800 (that was on Black Friday sale; it’s normally a kilobuck), you get a decent printer with two extruders and a heated bed. It fared average in Make magazine’s 2014 comparison, and I agreed with their assessment on the whole.

    So far, I’ve only printed PLA, and I’m happy with that. I have no reason at present to switch to ABS.

  2. The glass plate is from a dollar store picture frame. I had a choice between 5×7″ (smaller than the build platform) and 8×10″ (larger); I went smaller, which worked out well. A simple 1 mm shim was all I needed to adjust the platform height to offset the thickness of the plate.

    The printer comes with Kapton tape applied to the print bed, and I have a roll of it from which I’ve replaced the tape once, but now that I’m printing on glass, I don’t think I’ll go back to Kapton. I may change my mind if I start printing ABS.

  3. This is blue painter’s tape, on a corner of the print bed. Overrated, in my experience, but its terribleness at PLA adhesion is what makes it great for this specific purpose: prints I export with Simplify3D (more on that below) start with a glob of plastic in this corner, and having that land on painter’s tape makes it easy to remove whenever I want.

  4. The SD card came with the printer. I’ve never connected the printer to my computer; I always run it autonomously, using the controls on the front.

  5. I turn on this USB fan (Walgreens seasonal item) after a print to cool off the print and print bed. Once they’ve cooled enough, the part stops sticking to the glass and I can just pick it up—no pulling or prying required. This is the major advantage of glass.

  6. Hanging down into the printer is a wonderful little USB gooseneck strip light. The printer has its own lighting, but it’s top down, so the area under the extruders is in shadow. Lighting from the side gives me a better view of the print action.

  7. The cuticle nipper is among the tools I use to refine finished prints. They’re great for clipping off tiny burrs on edges and corners. I also have a nail file (they come in four-packs at the dollar store, and I don’t need that many nail files for my hands) that I use for similar purposes, including cleaning up where the cuticle nipper left off. Filing/sanding is one area where I feel my toolset is incomplete.

Not shown:

  • Two rolls of PLA. On the spindles are one “clear” (more like translucent) and one white. The white currently isn’t even loaded into the printer; I could swap in another spool at any time.
  • Other rolls of PLA. I have more white, some “natural” that I suspect may be equivalent to the “clear”, at least one spool of black, and half a kg of red (I want to make a pommel for Ikea’s red wind-up flashlight, and I want the colors to match).
  • A roll of PVA. I haven’t used it yet, but its use in 3D printing is as a support material in PLA parts. You can use PVA to support bridges and overhangs, then dunk the part in water to dissolve the PLA away.
  • The remaining Kapton tape.
  • Two spatulas. One is just a normal metal spatula from Daiso. The other is an extra-wide “fish” spatula from Target’s summer section, bought on clearance after summer ended. I’ve only used that a couple of times, and I basically haven’t touched either since switching from Kapton to glass.
  • Long cross tweezers, for extracting the odd bit of scrap plastic from the printer while the part is printing, or from the hot end while it’s still hot.
  • 15 cm ruler, and a digital caliper from Harbor Freight
  • Duster, for sweeping dust and bits of plastic off the print bed.
  • The USB charger that the USB hub is plugged into. (The fan and strip light are both plugged into the hub.) The charger is the one that came with the fan.

Several of the things I’m making are meant to be stuck to a magnetic whiteboard, so I’ve got stuff for that:

  • Magnets, obviously. I have strong permanent magnets—strong enough that the protective packaging is more protecting everyone and everything outside the package than protecting the magnets. A millimeter of plastic and a layer of silicone is enough distance to water them down to fridge-magnet pull.
  • Super Glue, of the brush-on type.
  • Disposable gloves, for handling the glue (“WARNING: BONDS SKIN INSTANTLY”) safely.
  • GE “100% silicone”, for added grip. (I’ve had mixed success with this so far. I may need to lay it on thicker than I’ve been doing.)
  • Plastic putty knives for applying the silicone to the parts.
  • Metal putty knives for removing the silicone from the plastic putty knives.

Software I use

I use OpenSCAD to design models—programmers will love it—and Simplify3D to slice and export the model for the printer. (Simplify3D exports G-Code; for a printer like mine, you’ll need GPX to convert it to an x3g file.)

UPDATE 2016-09-09: The version of Simplify3D I have now successfully exports x3g files on its own.

OpenSCAD is different from most 3D modeling software: It’s text-based. You describe your model in code, mainly using shape primitives and set operations (intersection, difference, and union), and then hit render to see what it looks like. When you’re done iterating, you do a final (longer-running) render, then export STL.

Simplify3D is a $140 slicing and printer control program. It’s both the best one out currently and ugly in a lot of places (especially the installer, which is a Windows-style “setup wizard”). It offers you a lot of control, which is both a blessing and a curse—but it means I can do certain things that I want that MakerWare wouldn’t let me, like crank the printer’s base print speed up to 125 mm/s (the default is 90).

So I write a model in OpenSCAD, export it to STL, bring that STL file into Simplify3D, export G-Code, and use gpx to convert the G-Code to x3g. I then put that x3g file onto the SD card to put into the printer.

Software I’ve tried and abandoned, or not tried at all

I’ve tried Cheetah3D, 123D Design, and Inventor Fusion. I found them all limiting in various ways; I frequently run into “I know what I want but either don’t have a tool that does that or the tool doesn’t want to let me do that” situations. OpenSCAD is bare-bones, but expressive.

I have not tried the successor to Inventor Fusion (which requires an internet connection, which makes no fucking sense for 3D modeling software), nor have I tried Blender.

I originally used MakerWare, and it was OK, but I find it hard to give up some of S3D’s more advanced features, like the speed control. I did have to export one part from MakerWare because Simplify3D seemed not to notice a long, very thin cylinder that was part of the model—but that’s the only problem I’ve had with S3D so far.

I’ll likely go back to MakerWare, at least initially, when I do my first dual-material (PLA+PVA) print. Simplify3D’s UI does not give me lots of confidence that it will handle that correctly without my needing to explain it some things.

I have tried Slic3r. Here’s a picture of me using it:

I have no idea what I'm doing.

I haven’t tried the newer “MakerBot Desktop” (successor to MakerWare), nor ReplicatorG, nor any of the other, older slicers.

I really want someone to come out with the iWork of slicers. Or modelers, but I’m happy enough with OpenSCAD that I’m likely not to want to put in the time to learn another GUI modeler, unless it’s a graphical editor for OpenSCAD files. But a truly nice slicer, with Simplify3D’s capabilities but much more refined and easy-to-use UI, would be great.

The to-do graph


2014-12-21 15:35:00 UTC

Earlier this year, I started practicing GTD.

I’m not very good at it yet. But I’ve learned some things.

And I’ve proven that lists suck.

A list is a single, flat, ordered collection of items. In GTD, you’ll have one list per project, and each item is an action.

This makes sense if you consider the list to be a record of everything you did toward that project, in order, written before instead of after.

But who does that?

Who micromanages the order of things they’re going to do before they do it?

Who has such perfect foresight?

Who has that kind of time?

Moreover, the order of a list is implicitly transitive: Every item in the list must come after every item before it and before every item after it.

That isn’t true: Some things can be done at the same time, or in either order. For example, you can work on assets while you install Xcode, and then you can work on assets before code or code before assets.

A list is a serial queue. No work can proceed until the work before it is finished.

The alternative to that is to throw out the ordering altogether: Put items in in the order you think of/receive them, and then every time you want to start one, scan through the whole list until you find something that you haven’t done and can do.

It’s a choice between false information—order relationships that don’t really exist—and no information.

The latter seems worse: Some of the orders are true, and therefore valuable, so why throw them all out?

How can we avoid that?

What makes the true orders true? Why do those actions have to be done before those other actions?


This action must be done before that other action because the other action depends on it.

Some actions depend on other actions. Some actions depend on multiple other actions.

This is a graph.

That’s what I’ve switched to. I still use OmniFocus (version 1), but only as an inbox; I migrate those items to my to-do graph, which I keep in OmniGraffle.

Example graph of two projects, “Build new app” and “Work on existing app”, with actions such as “Create Xcode project”, “Fix bug in frobulator”, and “Add BSP reticulation”.
You can tell this is a made-up example because some of these actions are not concrete enough to be proper GTD.

The graph enables me to express dependencies without making up false orderings. Items that can be done in parallel are in parallel.

I mainly edit the outline, rather than the boxes on the graph directly. You could use something like OmniOutliner or TaskPaper, but those can’t visualize the graph. OmniGraffle has an “auto layout” (no relation to the Cocoa feature) option that automatically creates and arranges boxes in the graph corresponding to items in the outline.

The top-level items in the outline, the roots of the graph, are goals. I typically write these as high-level imperative sentences such as “build initial version of app”.

All, or occasionally nearly all, of the other nodes are indivisible actions. Each is a single concrete step toward the goal.

The leaf nodes are “next actions”: At any time, I should be able to pick a next action as the next thing I’m going to do.

I also create nodes for other people’s actions that I’m waiting on. These nodes look like “So-and-so: Do such-and-such”. When that happens, I take it off; its parent—if it has no other dependencies—then becomes a next action.

I set OmniGraffle to lay the graph out as an upward tree, so that each project actually does look tree-like, with the “root” at the bottom.

To mark an action as done, I have two choices: I can set the node’s font to strike-through, or just delete it. I typically strike through my own completed actions, and delete obviated actions, completed actions by others, and completed goals.

You’ve gathered by now that OmniGraffle lacks some things for this.

  • It wasn’t designed to be used as a to-do list, so it lacks a concept of “done”. Instead of a checkbox, I have the Font Panel.
  • Similarly, there are no priority or due-date options. I generally don’t use these, but some projects do, in fact, have a due date, or greater or lesser priority than other projects, and it’d be helpful to track that.
  • The outline editor, which superficially looks like a mini OmniOutliner, lacks or changes about half of OmniOutliner’s keyboard commands. I really wish that if the keyboard focus is on the outline, that it would just respond exactly as OmniOutliner would to every possible keypress.
  • The option to have a node pinned to the far (top) row of the tree is a per-node option, so I can’t have it automatically lay out all next actions in the same row.
  • The outline structure, like OmniOutliner’s, means I cannot have multiple nodes depend on the same action—which they very well could in reality.

I have two points:

  • A graph is a much better way to express to-dos than a flat list.
  • There currently isn’t a Mac app ideally suited to this. OmniGraffle is a great graph editor, but I’m using it for a purpose it wasn’t designed for. I’d pay good money for an app of OmniGraffle’s quality and basic nature, but optimized for to-do keeping.

G4 Cube mods


2014-11-02 20:17:43 UTC

As some of you are aware, I own a Power Mac G4 Cube.

The G4 Cube was an impressive little machine from 2001. It was a Power Mac G4, minus any PCI slots, packed into an 8-inch by 8-inch by 8-inch (plus a few inches’ clearance underneath) cube. And it had no fan—it was cooled entirely by convection through the mostly-empty center column.

It’s also really fun to upgrade.

I’ve upgraded my Cube in three ways:


One of the old stand-bys, along with upgrading the processor and video card (both of which remain stock in my Cube).

RAM for a Cube is dirt cheap now, so I bought 1 GB. The theoretical maximum is 1.5 GB, but I’m only running Mac OS 9 on my Cube (all my personal OS X usage happens on my MacBook Air), so 1 GB should already be overkill.


The Cube, of course, came with a spinning-disk drive (a.k.a. “hard disk drive” or HDD), connected via ATA.

Replacing an HDD with an SSD is straightforward in most newer computers, but the Cube presents special challenges.

For one thing, it’s a desktop computer with a 3.5-inch drive bay, and SSDs are typically 2.5-inch (the “laptop” form factor). This would not be a problem if it were the only one, because adapter brackets exist, but it’s not the only problem.

Problem #2 is that the Cube uses ATA (now known as “parallel ATA” or PATA), whereas SSDs use serial ATA (a.k.a. SATA). Again, adapters exist, but that brings us to problem #3:


Not disk space, but physical space.

As I mentioned, the Cube is a lot of electronics packed into a small volume. The drive bay does not have free space on any side of it; it is exactly as big as needed to fit a 3.5-inch ATA hard disk drive.

This makes it difficult to impossible to fit a 2.5-inch drive, a PATA-to-SATA adapter, and an adapter bracket.

OWC sells SSDs with integrated adapters for pretty much exactly this purpose, but I cheaped out and went the DIY route.

  • I bought an 80 GB SSD off Woot.
  • I bought an adapter board at Fry’s. I think it was this one, but it was months ago and I’m not about to open up my Cube again to find out.
  • I bought an adapter bracket, I think from Amazon, but didn’t end up using it because of the aforementioned space constraints.

With a HDD, leaving everything flopping around inside the computer would be just asking for a problem, because the HDD has a motor, which will cause it and everything connected to it to vibrate. Sooner or later, the HDD could come unplugged (especially if it’s a 2.5-inch HDD), and then you just have bits pouring out all over whatever the Cube is sitting on.

But this isn’t an HDD; it’s an SSD. A Solid-State Drive.

It has no moving parts.

That’s what’s cool about having an SSD in a Cube:

No moving parts at all.

The Cube has no fan. The video card has no fan. The SSD has no motor. Thus, the entire set-up is completely silent.

The one downside is that since this drive is so large (by 2001 standards), the Mac takes awhile to validate that it is actually properly formatted. It actually shows the blinking question mark for a minute or two before it finally boots.


The stock video card in my Cube is a Rage 128 with ADC and VGA outputs.

I used to use my Cube on a contemporary Apple Studio Display that I could plug into the ADC port, but I don’t want to set up a second monitor specifically for that computer.

For sound, the Cube didn’t have a built-in speaker (no space) or audio jacks (presumably no space even for that). Instead, it came with a custom Apple speaker set-up consisting of a central DAC box with hard-wired USB and speaker connections on one side and a headphone jack on the other.

Mine’s in somewhat shabby shape, and I don’t want to use it anyway.

I have a Yamaha AV receiver, Monoprice 5.1 speakers, and an Optoma 1080p projector. The receiver and the projector both support HDMI. What I really want is to be able to route the Cube’s audio and video together into one of the receiver’s HDMI ports, so that the Cube can be alongside my PS3, my iPad, and my MacBook Air as possible external sources to be presented through the receiver’s speakers and the projector.

And that’s what I have.

This adapter takes video input over VGA and audio input over USB, and outputs HDMI.

It’s an HDMI port for the G4 Cube.

Yes, the ideal solution would use digital video from the ADC port, but nobody’s going to make such an adapter for ADC today. A DVI one could exist, but would probably be way more expensive, and require also purchasing an ADC-to-DVI adapter cable.

The VGA output looks fine. The Cube can output up to 1600×1200, and it looks great on my wall.

The only real drawback is that Mac OS 9 (or maybe the video card) never heard of 1920×1080, so I can’t actually output the native resolution of my projector.

My wonderful Cube

My G4 Cube has 1 GB of RAM, an SSD with more free space than I know what to do with, and an HDMI port, to which I’ve connected a 1080p projector and 5.1 speakers.

And it’s completely silent. (Although admittedly the projector ruins that.)

It’s a cool little machine.



2014-10-25 09:50:47 UTC

The blog’s back up. It’s been down most of the year, as rather a lot of you noticed.

Thank you, everyone who told me. Every time you told me my blog was down, you were also telling me that you missed it, or at least you needed it for something. You’re part of why I kept meaning to bring it back, and why I eventually did.

I work for Apple now.

I’m on the Foundation and Core Foundation team, which is part of Cocoa. Part of my job is reading the Radars you file about those two frameworks and making sure they go to the right people.

I live in San Francisco now.

I moved early in the year, not long after I had to change hosting providers after TextDrive breathed its last (that was why the blog went down in the first place) and shortly before I started at my job.

I moved for the job; I work in Infinite Loop.

(I also moved because I love San Francisco. I’ve been here a couple of times before, and fell in love with it when I first stepped out of Civic Center BART onto Market Street.)

I probably won’t write as much here anymore.

A big part of that is time constraints: Subtract the job, the commute, three square meals, and sleep, and I don’t have a lot of time in a day to pound out a blog post.

Then, of course, there’s the nature of the job: Being at Apple means I know some things that aren’t public. Not a lot, but enough. Better to be careful than accidentally say something here that I’m not supposed to.

The same goes for my being active on Stack Overflow.

You’re welcome to ask a question and send me the link, but somebody else will probably get to it before I will.

And, of course, MacTech. See above. (If you have a subscription, you might have noticed this already—my last article ran in August, I think.)

I won’t be at MacTech Conference this year, either. This is the first time in the conference’s history that I won’t be at it. But plenty of other fine folks will who are worth listening to and who are good company.

That’s all I have to say for now. For those of you who use Twitter, I’m still there.

Until next time.

Simple starter Cocoa app ideas


2013-12-11 13:46:20 UTC

Inspired partly by tonight’s Hour of Code, here are some index-card-sized outlines of some simple app projects you can make as someone new to Cocoa.

Text editor/word processor

  • Document-based Mac app
  • In document window: NSTextView
  • Use NSAttributedString to read/write document data
  • Document types:
    • public.plain-text
    • public.rtf
  • Extra credit:
    • Add a ruler (NSRulerView)

Picture viewer

  • Document-based Mac app
  • In document window: IKImageView
  • Use CGImageSource to read image (picture) & its properties
  • Document types:
    • public.png
    • public.jpeg
  • Extra credit:
    • Floating inspector panel showing the properties in an NSTableView
    • Color-correction panel (IKImageEditPanel)
    • Support folders (public.folder): display images from folder in IKImageBrowserView

PDF viewer

  • Document-based Mac app
  • In document window: PDFView
  • Use PDFDocument to read from .pdf file
  • Document types:
    • com.adobe.pdf
  • Extra credit:
    • Toolbar with zoom in/out buttons, zoom % field, page number field

Requirements for a true Mac keyboard


2013-09-06 21:09:47 UTC

With the Mac undergoing a resurgence in popularity, keyboard manufacturers have started to release Mac versions of their hitherto Windows-only products.

Of course, USB helps; it’s been possible for 15 years to use Windows keyboards on a Mac. But I don’t think any Mac user wants the reminder of looking down and seeing that logo staring back up at you.

Moreover, just as certain things—including that key—make a Windows keyboard a Windows keyboard, there are certain things that make a Mac keyboard a Mac keyboard.

Unfortunately, the Windows keyboard manufacturers tend to forget most of them and screw up others.

My bias: The keyboard I hold up as the standard

The Apple Extended Keyboard II.
(This is John Gruber’s; his photo was better than any of mine.)

When I evaluate how much of a Mac keyboard a keyboard is, I compare it to this.

The most obvious sign of a Windows keyboard

… is, of course, the plus key on the numeric keypad.

Here’s the Das Keyboard Model S for Mac:

Das Keyboard for Mac keypad
Doubleplus ungood

Compare to the keypad from the Apple Extended Keyboard II above.

To enumerate the differences:

  • Where a Windows keypad has NumLock, a Mac keypad has Clear. (Das Keyboard’s Mac model gets this much right.) Extended keyboards often have the Clear key bear both labels (as on the AEK2), since it may be used as NumLock in a PC emulator or virtualizer.
  • The Mac keypad inserts an equals key immediately to the right of the Clear key. The operator keys remain in the same order (/ * – +), but are shifted over to the right and down.
  • To make room for the equals key, the Mac keypad’s plus key takes up only a single row.

Oh yeah, and the modifiers

PC keyboard manufacturers tend to only do this halfway.

The modifier keys in the bottom-left corner are:

  • On a Mac keyboard: ctrl, option, ⌘
  • On a Windows keyboard: ctrl, Windows, alt

Plug either one into the wrong kind of computer, and the Option key is Alt (or vice versa) and the ⌘ key is the Windows key (or vice versa). Thus, Option/Alt and ⌘/Windows will be backwards.

There are two differences that PC keyboard manufacturers almost always miss:

  • On a Mac keyboard, the option key is slightly smaller than its two neighbors. The ctrl key should be the same size as ⌘.
  • A Windows keyboard may have four keys in the lower-right corner: between alt and ctrl, a key to right-click the mouse. (Apparently there are Windows users with one-button mice?!) A Mac keyboard has exactly three modifier keys on the bottom row in each corner.

All too many Mac versions of Windows keyboards have all three modifiers the same size, as the original Windows models do, and some even still have four keys in the lower-right corner (with the fn key in the place of the right-click key).

It’s also unfortunately common for the ⌘ key to be labeled “Command” rather than with the ⌘ symbol. (Both the Das Keyboard and Unicomp’s SpaceSaver M are guilty of this.) If you can put a Windows logo on your Windows key, you can put a ⌘ symbol on your ⌘ key.

The fn key and media keys

I’m of two minds about this.

On the one hand, you saw my standard up there. Ain’t no fn key on that. I’ll be happy to never see one on a desktop keyboard.

On the other hand, we do live in the Mac OS X era, with NeXT-inherited (and other) media keys on our keyboards, generally placed on the function keys. A keyboard so equipped needs a fn key to distinguish between media-key presses and function-key presses.

I’ve seen several variations of fn key placement:

  • Apple, as we all know, puts it in the lower-left corner on their laptops and wireless keyboards. Most Bluetooth keyboards that advertise Mac compatibility (as opposed to Windows or iOS) do likewise. Since this is where Apple puts theirs, if you’re making a Mac keyboard with an fn key, this is where you should put yours.
  • NeXT’s keyboards didn’t have function keys, but they did have four of the media keys: volume up and down, and brightness up and down. They had a power key, too, in between the pairs of volume and brightness keys. All five were in place of the navigation block (home, page up/down, etc.). The end key was gone entirely. (We won’t get into NeXT keypad layouts.)
  • The Das Keyboard replaces the right-click key with this. Having it in between two modifier keys is supremely weird—even just putting it in the lower-right corner would have been better.
  • Unicomp’s Spacesaver M does the same as the Das Keyboard.
  • Older versions of Matias’s Tactile Pro (which is billed as a successor to the AEK2) do not have an fn key. They put the volume keys and Eject key at the top-right, and have no other dedicated Dashboard, Spaces, Exposé, etc. keys.
  • Apple’s current wired keyboard and Matias’s Tactile Pro 4 (the current version as I write this) replace the Help key with an fn key.
  • The Mini Tactile Pro puts it immediately above the right arrow key/to the right of the up arrow key. Downside: Very easy to enter dictation mode when up- or right-arrowing repeatedly.

(Incidentally, I think the Mini Tactile Pro makes some very clever choices overall. I still won’t give up my keypad, though.)

Make sure you implement your fn key correctly, lest your users suffer the consequences. (The keyboard that Nicholas Riley was referring to in that tweet was the Logitech K760.)

The return key

Should always be labeled “return” (or “⏎”), never “enter”. Enter is on the keypad; Return is in the main keyboard.

If you have a fn key, fn-return should be Enter, exactly as on Apple’s laptops. I don’t care about this for extended keyboards, but for a compact keyboard, it’s a requirement, and if you have an fn key anyway, better to support it than not. If nothing else, it’s an affordance to heavy laptop users, who’ll be used to fn-return as a habit.

The power key

My standard keyboard, of course, has a power key, so, on a learned-behavior level, I still expect it from a true Mac keyboard.

On the other hand, it doesn’t actually power the machine on anymore (USB ports are dead on a turned-off Mac), and the Eject key can sub for it in all the old n-finger salutes, so it really is disposable.

Perhaps the power key’s remaining value is sentimental. It’s a testament. It says “this is a Mac keyboard, dammit—we didn’t just reskin our Windows board; we made one for you”.

Or: Perhaps the Eject key should replace the power key, exactly where it is. It does all of the power key’s surviving functions, and is likewise characteristic of (modern) Mac keyboards; therefore, it should be in the same place. (The Tactile Pro 4 does this, not surprisingly.)

The help key

Kill it with fire. I’ve never seen a real application make any use of it; all it does is enter a mode of unhelpfulness.

Possible alternatives:

  • Make it unconditionally an Insert key (assuming this is possible at the hardware/HID level).
  • Replace it with Eject. (Potentially problematic, considering what unmodified Eject does.)
  • Replace it with fn.
  • Replace it with the world’s smallest ashtray.

The baselines

Most character-generating keys—the letter, punctuation, and number keys—have two baselines. Punctuation keys use both of them, and, on most keyboards, keys marked with only a single character use only one of them.

On older Mac keyboards, single-character keys use the lower baseline. This includes the letter keys, the operator and number keys on the keypad, and the return and enter keys. Indeed, virtually all keys on a previous-generation Mac keyboard are labeled on the lower baseline, except for the punctuation keys. Also, on all Mac keyboards, all keys are the same color.

On a PC keyboard, things are a little more complex.

Annotated cropped photo of the Unicomp SpaceSaver M's letter board, showing the baselines of white keys (such as letter, punctuation, and number keys) and gray keys (such as delete/backspace, return, and shift).

Unicomp’s visual design is consistent with that of the classic IBM keyboards, which is much of Unicomp’s appeal (particularly among PC users). There is clearly a system there:

  • Keys are divided into white keys and gray keys. White keys all generate characters. Most gray keys do not; most of them are modifiers (like shift), and the others include backspace, enter, and the right-click (fn on the SpaceSaver M) key. Curiously, the keypad operator keys (which all insert characters) are also gray keys.
  • Single-character white keys use the higher baseline, not the lower, whereas gray keys are vertically centered.

Apple’s newer keyboards are in the middle. All keys are still the same color, but there’s a typographical division between “white keys” and “gray keys”. Most of the keys that generate most of the characters are biaxially centered, whereas “gray keys” are aligned to a bottom corner. Keys labeled with only a symbol have it in the center, whereas most of the word-labeled keys are labeled in a corner, except for esc and the navigation keys.

So, if I had my way, keyboards would have lowercase letters on the lower baseline. The numbers on the keypad should be the same (as they are on older Mac keyboards).

As it is, any keyboard that has letters (and keypad numbers) on the upper baseline sticks out as a PC keyboard in Mac keyboard’s clothing.

And then we come to the SpaceSaver M’s keypad:

Baselines on the SpaceSaver M's keypad. All of the white (number and period) keys are consistent with the other white keys, and *most* of the gray keys are vertically centered—but not all.

Most of the gray keys are consistent with gray keys everywhere else on this board (and on PC keyboards in general). But what happened with the minus and plus keys? The minus sign is on the upper baseline, consistent with the white keys to the left of it, and the plus sign is on the lower baseline!

(The minus sign is doubly weird when you consider that their PC keyboards have a single-height minus sign that is consistent with the other gray keys. Again, what happened?)

I suppose I should not be surprised that the odd keys out are the ones that replace the double-height plus key on a PC keypad. Although, in Unicomp’s defense: At least they bothered to have a Mac-layout keypad at all, unlike most PC keyboards for the Mac.

The visual design

Most keyboards look about as decent as any other, but the SpaceSaver M and Das Keyboard both stumble here.

Das Keyboard’s failing is just the ugly, low-legibility font used for the keys. Check out the apostrophe/quote key:

Das Keyboard for Mac apostrophe/quote key. The quotation mark looks more like a single short horizontal line.
This is cropped from a 3000-pixel-wide photo.
Yes, that really is the quote mark up top—this is not the accent/tilde key.

Then there’s Unicomp’s SpaceSaver M. Check out its media keys:

Media keys (most of the function keys) on the SpaceSaver M. F1 and F2 are brightness; F3 is Exposé (seemingly labeled “Expose´” with the accent mark after the e); F4 is Dashboard; F7 through 9 are playback controls; F10 through 12 are volume controls.

The brightness symbols are decent enough, I guess. Nothing wrong with the playback keys, except that that pause symbol needs to eat a sandwich.

But look at “Expose´” and “Dashbrd”. Those two keys in particular strike me as lazy—like, you couldn’t plot some rectangles? If nothing else, you couldn’t type a proper é? And why “Dashbrd” and not, if you’re going to abbreviate, simply “Dash”?

And those speakers! Those are not speakers. Those are funnels. Sideways funnels with dots and waves rising out of the intake for some reason.


The lights section in the upper-right corner of the SpaceSaver M. It has two lights: One for caps lock (labeled “A🔒”), and the other labeled “Fcn”.


Visual design is a low priority in keyboards in general, but needs to be a high priority in a high-end keyboard. The keyboard may not be a part of my system that I regularly look at, but if your keyboard is a high-end product, then it ought to look high-end. It ought to look badass and/or pretty. I ought to be able to brag about it and show pictures and have people be suitably impressed.

And remember: The first test of your keyboard is when I look at it on the web. I can’t type on it yet, so the only test I can apply is whether it looks good. Don’t fail that early.

(Incidentally, this blog post from last month shows a SpaceSaver M that looks quite different from the picture on Unicomp’s website: The left option and right “Function” keys are way smaller (too small, I say); “Expose” loses its fakey accent mark, “Dashboard” is fully spelled out, and both of them are set in a condensed font; etc.)

So what does a modern Mac keyboard look like?

If you make keyboards, this is the keyboard I want to buy from you.

A mockup of my dream keyboard's layout, made by modifying a screenshot of the OS X Keyboard Viewer window.

  • Mechanical key switches or GTFO. Ideally, somehow license Unicomp’s buckling-spring switches (or be Unicomp). Second-ideally, perfectly mimic the AEK2 keyswitches (like the Tactile Pro purportedly does). But, at the very least, your key switches need to have non-linear, tactile response. My keyboard should be loud.
  • It must be an extended keyboard. I will do without a keypad when I’m on a laptop, but when I’m sitting at my desk, I make full use of the ten-key.
  • Ctrl and ⌘ should be the same size as the tab and backslash keys. Option should be slightly smaller.
  • You should have at least a Caps Lock light, and ideally should have all three lights (they can be controlled by software).
  • Kill off the Help key. This is the one bad thing about the AEK2. Any of the alternatives mentioned above would be a welcome improvement. I nominate the fn key.
  • The Power key’s rightful successor is the Eject key; therefore, it should be in that place, in the top-right corner.
  • The media keys get to live. I, for one, do use the volume keys on my laptop, and I’m sure some folks use the Exposé keys (and I have been known to use Exposé-current-app sometimes). Ideally, I’d like to see these be separate keys, above the function keys, like on certain Windows keyboards. (But not mushy rubber buttons. All keys should be real keys.) But I wouldn’t dismiss a keyboard that satisfied all of the other requirements just because it required fn+function keys to access the media keys.
  • It must implement the fn key properly (unlike the Logitech keyboard mentioned above). Double-fn for dictation should work, and the setting to switch function keys and media keys should be respected.
  • Ideally, the keyboard should look good, too (more Tactile Pro, less SpaceSaver M).

Updated 2013-09-07 to cover a couple of aspects of newer Apple keyboards that I missed. Thanks to Jason Clark and Jens Ayton for pointing out my omissions.

How to read what I’ve been writing


2013-08-11 19:04:07 UTC

You might have noticed that this blog of mine has gotten mighty quiet on the sort of programming-related (especially Cocoa-related) topics I historically have written about here.

There have been, and will continue to be, occasional exceptions, but, for the most part, this will remain the case for the foreseeable future.

So, where do I write about programming nowadays?

MacTech magazine.

Cover of the August 2011 issue of MacTech magazine.
The first issue with an article of mine in it.

Here’s some of what I’ve written about:

  • C and Objective-C basics
  • Introduction to NSOperationQueue
  • Uses of GCD besides dispatch_async (this one was split over two issues)
  • How Cocoa and Cocoa Touch use blocks
  • A sampling of available developer tools, both Apple and third-party (co-written with Boisy Pitre)
  • Reviews of developer documentation viewers
  • Using Quick Look
  • Practical applications of Core Image

If you want to read my previous articles, they sell old print issues for $10 each, and they sell old issues from January 2012 onward in their iPad app for $5 each.

If you want to read future articles, it’s cheaper to subscribe: iPad subscriptions are $11 (in-app) for three months, and print subscriptions are $47 for a year (or cheaper with certain coupons).

I’ve got some good stuff coming up. The immediate next thing is a two-parter on essential tools and best practices for developers. Part 1 should be in the August issue.

  1. If the object may come in a mutable variant (like NSString has NSMutableString), use copy, so that you don’t end up holding a mutable object that somebody mutates while you’re holding it.

  2. If you will own the object, use strong. (Optionally, leave it out, because strong is the default for objects.)

  3. If the object will own you, use weak. For example, a table view weakly references its data source and delegate, because they are very often the VC or WC that indirectly owns the table view.

  4. If the object cannot be referenced with a true weak reference, use unsafe_unretained. A select few classes*, such as NSTextView, do not support weak references. You will get an exception at run time if you try to establish a weak reference to such an object. You will have to use unsafe_unretained instead.

    The reason weak is preferable is because, if the object dies while being weakly referenced, the weak references automatically get changed to nil. That’s also the part that certain classes are allergic to. unsafe_unretained doesn’t have this feature, which is why the classes that don’t support weak can still be referenced with unsafe_unretained—but, the caveat is that if you use unsafe_unretained, you must ensure that the object will never get deallocated while you are weakly holding it—i.e., that you let go of your unsafe unretained reference before the last owner of the object lets go of that ownership.

  5. Never use assign. For objects, unsafe_unretained is synonymous and clearer (it explicitly says that it is unsafe, which it is). For non-objects (such as NSUInteger and CGFloat, leave it out—assign is the default for such values.

* The Transitioning to ARC FAQ includes a complete list of classes that do not support weak references.

(This is an expanded version of a comment I posted on Stack Overflow.)

How trigonometry works


2013-06-10 15:48:12 UTC

I’ve never been a very mathy person, and I came to trigonometry particularly late in life—surprisingly so, considering I’m a programmer who has to draw graphics from time to time. (Guess why I started learning it.)

So, for folks like me who can’t read Greek, here’s an introduction to trigonometry.

Trigonometry largely revolves around three basic functions:

  • Cosine
  • Sine
  • Tangent

You know these from the famous mnemonic acronym “SOHCAHTOA”, which is where I’ll start from.

The acronym summarizes the three functions thusly:

  • sine = opposite / hypotenuse
  • cosine = adjacent / hypotenuse
  • tangent = opposite / adjacent

Very buzzwordy, and nonsensical when every time you use them, you pass in an angle. And yet, 100% correct.

The cosine, sine, and tangent functions work by creating an imaginary triangle whose hypotenuse has the given angle, and returning the ratio of two of that triangle’s sides.

Given the angle of 30° (or π × 30180 radians, or τ × 30360 radians):

Diagram of a right triangle of 30° within a circle

All three functions create this triangle, and then return the ratio of two of its sides.

Note the proximity of the three sides to the origin.

  • The opposite side is the vertical side, literally on the opposite side of the triangle from the origin.
  • The adjacent side is the horizontal side, extending from the origin to the opposite side. It’s the adjacent side because it touches (is adjacent to) the origin.
  • The hypotenuse is the (usually) diagonal side that extends from one end of the adjacent side (namely, from the origin) to one end of the opposite side (namely, the end that isn’t touching the other end of the adjacent side).

Let’s consider a different case for each function—namely, for each function, the case in which it returns 1.


Definition: adjacent / hypotenuse

Circle with a 0° triangle from its center

With the hypotenuse at 0°, there basically is no opposite side: The hypotenuse is in exactly the same space as the adjacent side, from the origin to the lines’ ends. Thus, they are equal, so the ratio is 1.


Definition: opposite / hypotenuse

Circle with a 90° triangle from its center

With the hypotenuse at 90° (or τ/4), there basically is no adjacent side: The hypotenuse is in exactly the same space as the opposite side, from the origin to the lines’ ends. Thus, they are equal, so the ratio is 1.

Cosine and sine: What if we swap them?

Try sin 0 or cos τ/4. What do you get?

Zero, of course. The 0° triangle has effectively no opposite side, so the sine of that (tri)angle is 01, which is zero.

Likewise, the 90° triangle has effectively no adjacent side, so the cosine (adjacent/hypotenuse) of that (tri)angle is 01.


Definition: opposite / adjacent

You should be able to guess what the triangle for which tangent returns 1 looks like. Go on, take a guess before you scroll down.


















Circle with a 45° triangle from its center

A 45° (tri)angle’s adjacent and opposite sides are equal, which is what makes the tangent function return 1.

Cosine and sine: The unit circle

Cosine and sine return the ratio of one side or the other to the hypotenuse.

Accordingly, the length of the hypotenuse affects the result. But, again, these functions take only an angle, so where do you tell it what hypotenuse to use? And why do these functions, on any calculator and in any programming language, return only a single number?

The trigonometric functions are defined in terms of the unit circle, which is a circle with radius 1.

If you look at the diagrams above, you’ll notice that the hypotenuse of the triangle always extends to the perimeter of the circle—that is, it’s always equal to the radius. This is no accident: The hypotenuse of the constructed triangle is the radius of the circle. And since the radius of the unit circle is 1, that means the hypotenuse of the imaginary triangle is 1.

Thus, the fractions that cosine and sine return are adjacent / 1 and opposite / 1. That’s why they return single numbers: the “/ 1” is simplified out.

From this follows the method to compute cosine or sine for an arc with a different radius: Multiply the cosine or sine by the desired radius.

Cosine and sine: What if we use an angle greater than 90°?

What happens if we take the cosine and sine of an angle like, say, 4 radians (about 230°)?

Let’s draw out the triangle:

Circle with a 230° triangle from its center

Geometrically, the origin is 0,0. As long as we’re in the 0–90° range, no problem, because both the x (cosine) and y (sine) values in that quadrant are positive. But now we’re in negative territory.

With the hypotenuse in this quadrant, the adjacent and opposite sides are now negative numbers. cos π = cos τ2 is -1, and sin (τ×34) is likewise -1. For this triangle, they’re similarly negative, though not -1.

(Exercise: What about the other two quadrants? What are the cosine and sine of, say, 110° and 300°?)

Tangent: What if we use an angle greater than 45°?

As we saw above, if we give the tangent function an angle of τ/8, the ratio is 1. What if we go higher?

Well, then the ratio goes higher. Very quickly.

Graph of tan(x) for x = 0 → τ/4

The half-curve at left is the quadrant from 0 to τ/4 (the upper-right quadrant).
The curve in the middle is the two quadrants from τ/4 to τ×34 (the entire left half of the circle).
The half-curve at right is the quadrant from τ×34 to τ (the lower-right quadrant).

In words, the tangent function returns a value from 0 to 1 (inclusive) for any angle that is a multiple of π plus or minus τ4 (45°). 0 counts (it’s 0π), as does π, as does π2 (= τ = 360°), and so on. Likewise 45°, 360-45=315°, 180-45=135°, 180+45=215°, etc.

Segmentation of a circle by what sort of values tan(x) returns

Outside of those left and right quadrants, the tangent function curves very quickly off the chart—it approaches infinity.

(Programmer note: In some environments, there are both positive and negative values of zero, in which case tan 0 returns positive zero and tan π returns negative zero. Mathematically, there is only one zero and it is neither positive nor negative.)

Tangent is the only one of the three that can barf on its input. Namely, a hypotenuse angle of τ/4 (90°) equates to the opposite (vertical) side being 1 and the adjacent (horizontal) side being 0 (as shown above for the sine function), so tan τ4 = 1/0, which is undefined. The same goes for tan τ34, which equates to -10.

The tangent of an angle is its slope, which you can use to reduce an angle down to whether it is more horizontal (-1..+1), more vertical (< -1 or > +1), perfectly horizontal (0), or perfectly vertical (undefined).

As a practical matter, whenever I need to compute a slope ratio, I special-case perfectly vertical angles to result in ∞.

Cosine and sine: Width and height

From the above definitions, the practical use of cosine and sine emerges: They return the width and height of the right triangle whose hypotenuse has that angle.

As described above, these results are typically interpreted in terms of the unit circle (a circle with radius 1), meaning that the hypotenuse of the triangle is 1. Thus, if you’re working with an arc or circle with a different radius, you need to multiply your cosine or sine value by that radius.

A practical problem

For example, let’s say your friend has a 50″ TV, and you’re wondering what its width and height is. Maybe she’s moving, or giving or selling it to you, or both, so one of you is going to need to know whether and where it’ll fit.

The length of the hypotenuse is the radius of the circle; in the unit circle, it’s 1, but we’re dealing with a hypotenuse (diagonal measurement of the screen) whose length is something else. Our radius is 50″.

Next, we need the angle. No need for a protractor; TVs typically have an aspect ratio of either 16:9 (widescreen) or 4:3 (“standard”). The aspect ratio is width / height, which is the inverse of the slope ratio: the ratio that the tangent function gives us (which is opposite / adjacent, or height / width). Dividing 1 by the aspect ratio gives us the slope.

Only problem is now we need to go the opposite direction of tangent: we need to go from the slope ratio to the angle.

No problem! That’s what the atan (arctangent) function is for. (Each of the trigonometric functions has an inverse, with the same name but prefixed with “arc” for reasons I have yet to figure out.)

atan takes a slope ratio and gives us, in radians (fraction of τ), the angle that corresponds to it.

Let’s assume it’s an HDTV. (I don’t want to think about trying to move an old 50″ rear-projection SDTV.) The aspect ratio is 16/9, so the slope is 9/16 (remember, tangent is opposite over adjacent); atan 916 is about 29–30°, or about 0.5 radians.

Diagram of a right triangle of 30° within a circle

I promise that my choice of 30° for the first example and subsequently deciding to measure an HDTV as the example use case was merely a coincidence.

So we have our angle, 0.5 radians, and our radius, which is 50″. From this, we compute the width and height of the television:

  • Take the cosine and sine of the angle. (Roughly 0.867 and 0.577, respectively, but use your calculator.)
  • Multiply each of these by 50 to get the width and height (respectively) in inches. (Roughly 44″ and 29″, respectively, rounding up for interior-decorative pessimism.)
  • Add an inch or two to each number to account for the frame around the viewable area of the display.

So the TV needs about 45 by 30 inches of clear space in order to not block anything.

More good iOS games


2013-05-25 17:48:32 UTC

Inspired by this post from last year by Mike Lee, here’s a list of the best games from my iOS app library.

Many games are excluded, for any of these reasons:

  • Games on this list must not be violent (e.g., I excluded Carmageddon and even Bastion, Sonic 2, and Sonic 4)
  • Games on this list must not be Zynga-tastic (e.g., I excluded Draw Something)
  • Games on this list must not be on last year’s list (see Mike’s post)

Also, I’ve restricted myself to iOS games. Some of the games below are available on multiple platforms, but all of the links are to the iOS App Store.

The games

(Enigmo violates the “not on Mike’s list” requirement, but I gave it a pass for two reasons: because I linked to both the iPhone and iPad versions, and because I linked to the sequel.)

A language-contrast exercise


2013-03-31 14:59:34 UTC

Python’s str type has a translate method that, given a second string representing a translation table, returns a new string in which characters in the first string are looked up at their ordinal positions in the translation table and replaced with the characters found at those positions.

The identity translation table, performing no changes, is table[i] = i. For example, table['!']* is '!', so exclamation marks are not changed. If you made a table where table['!'] were '.', exclamation marks would be changed to periods (full stops).

I’d like to see implementations of a program that does that, with the input string encoded in UTF-16 and the translation table encoded in UTF-32 (a 0x11000-element long array of UTF-32 characters), with the table initialized to its identity: table[i] = i.

And yes, you need to handle surrogate pairs correctly.

Some languages that I would particularly like to see this implemented in include:

  • C
  • Haskell
  • LISP
  • A state-machine language (I don’t know of any off-hand; this might be their time to shine)

I know how I would do this in C, and I’m sure I could bash something out in Python, but how would you do this in your favorite language?

As a test case, you could replace “ and ” (U+201C and U+201D) with « and » (U+00AB and U+00BB).

If you want to post code in the comments, <pre>…</pre> should work. Alternatively, you can use Gist.

* I’m using the C sense of '!' here. In Python, this would be table[ord('!')], since characters in Python are just strings of length 1, and you can’t index into a string with another string; ord is a function that returns the ordinal (code-point) value of the character in such a string.