Although I’ve written more about Cocoa than Carbon, my professional gig is usually the opposite. My experience is in (often large) commercial shrink wrap software, which, at this point, is usually written in Carbon. Because of this, I recently had to opportunity to discover what it takes to print to PDF in a Carbon application. Of course, by “opportunity” I mean excruciating, unending pain.

It turns out that you only need one API to change your print loop to dump out to a PDF:

extern OSStatus
  PMPrintSession      printSession,
  PMPrintSettings     printSettings,
  PMDestinationType   destType,
  CFStringRef         destFormat,
  CFURLRef            destLocation);

It’s defined in PMCore.h, and even has documentation for it in the headers. You simply pass in the print session and settings, then specify kPMDestinationFile for the destination type, kPMDocumentFormatPDF for the destination format, and then a CFURLRef for the location of the PDF file.

Easy huh?

Unless you have to go find this API for yourself. i.e. You want to print to a PDF, but don’t know what API will actually do that. You see, the Print Manager documentation is part of Apple’s patented Don’t Document a Damn Thing initiative. And as I can attest, it’s a resounding success.

I searched through the headers (which still draws bizarre stares from Windows people. “You mean Apple doesn’t like developers enough to even provide real documentation?”), but couldn’t find anything that actually did what I needed. I googled for it too, but to no avail. I eventually found the API by digging through an email list archive.

Carbon documentation is apparently highly classified information at Apple. No one is supposed to know about it, let alone talk about it. It’s approximately at the same level of secrecy as the Freemason’s secret handshake. Except that I assume Apple would dispatch someone to take you out if you discovered any information on the Carbon API’s. That’s the only reason I can determine for the sparseness of documentation.

Unless you buy the other reason I’ve heard: Cocoa is the way of the future, so it doesn’t benefit Apple to document the old APIs. I mean, obviously, since I can’t figure out how to do something in Carbon, I should just port this 500kloc+ application to Cocoa. After all, we all saw Steve port an entire application by just checking a little box. And remember that demo where they build an entire word processor without writing a line of code? Why can’t you be that good?

What I’m thankful for this year: bitterness.