Borkware Miniblog

August 15, 2011

The New Phone Books Are Here! The New Phone Books Are Here!

Filed under: amosxp, Big Nerd Ranch, writing — Mark Dalrymple @ 11:56 am

Vikki bookIt’s been a while in the making, but Advanced Mac OS X Programming 3 / The Big Nerd Ranch Guide has finally started trickling out to folks.  I got my Author Copies today.  WOOOO!  You can see Vikki posing with the new edition.  Everything on the internet is improved by adding a cat.

This book is a massive overhaul of the second edition.  I dropped a number of chapters (I’m pretty sure folks know about version control systems these days), and a number were added (DTrace and GCD anyone?), with pretty much everything edited and improved (bye-bye Shark :-(  Hello Instruments :-) ), covering stuff through 10.6 / iOS 4.  Students taking my class at the ranch get to be guinea pigs a sneak peek of the Lion-related material.  It had already been over five years since the second edition, so we decided to go ahead and ship it, and then do a thorough job on the Lion / iOS5 / iCloud stuff in a later edition.  Hopefully not so much later this time.

Speaking of Editing, Susan and Chris Loper from Intelligent English edited the book and maintained the DocBook-based pipeline of tools.  The second edition did not have an editor, and it shows.  Chris wrangled the tools, and thanks to Susan’s work I’m quite proud of the third edition, the quality of the writing, and the quality of the index (another second edition sore spot).

These things make great Labor Day gifts.  Be sure to order several for the children.  I’ll have a couple with me at CocoaHeads/Pittsburgh this week to give away.

Edit2: Gaige Paulsen pointed out that it’s already available in the iBooks / Kindle stores.  You can snarf the free sample and check out the table of contents.

Edit1: Folks have asked what’s new (skimming down the ToC – I’ve been living inside this thing, and teaching out of it for five years now…)

  • ObjC 2.0 stuff, properties, etc
  • Blocks
  • 64-Bit computing
  • getopt_long
  • lib/otool
  • Garbage Collection
  • Debugging techniques
  • DTrace
  • Overhaul of Performance Tuning
  • Instruments
  • NSFileManager got a complete overhaul
  • IPv6, overhaul of the code
  • CFHost
  • FSEvents
  • Operations
  • GCD

June 14, 2011

Scrivener for long-form technical writing

Filed under: amosxp, meta, Random, writing — Mark Dalrymple @ 6:00 pm


Every now and then I come across a software tool that Gets It. A tool that does everything right. A tool that is a joy to use. VoodooPad is one. MarsEdit is another. Scrivener is the latest to enter the pantheon of My Favorite Apps.  The last three big chunks of new stuff for AMOSXP(3), (GCD, using Instruments, and a re-write and major updating of NSFileManager) were organized and written in Scrivener, and then later converted to DocBook for inclusion in the book. In all, about 18,000 words worth of work.

Scrivener is a non-linear text editing environment. Rather than having, say, a chapter of a book in one single Word or Pages document, you can have each section or sub-section of that chapter in an entity. You can organize these entities in an outline, and Scrivener will automatically flow the text as if it were a larger document. Each entity can be as long or as short as it needs to be.

For example, this is the “binder”, the outline view, for the new GCD chapter:

Dispatch binder

It has all of the sections of the chapter. If I’m wanting to edit the text for Dispatch Groups, I can select it in the Binder and focus in only on that text. If I wanted to make sure that the text flows into and out of that section, I can multi-select Time, Dispatch Groups, and Semaphores, and see those three sections of text in one editing panel, with subtle separators between the sections. If I decide that I really should talk about queues before terminology, I can just drag the entity and rearrange things. This feature alone, to me, is worth the low price of admission ($45).  Doing major surgery like that in a single document is fraught with peril.  With Scrivener, it’s drag and drop.  Don’t like it?  Undo it.

In addition to seeing the text, and a standard wordprocesor-style outline view (which I don’t use), there’s a cool corkboard mode. I originally thought it was silly and gratuitous, but I eventually found it to be a nice (and fun) way to play with the organization of the document. The corkboard mode also shows metadata, such as a high-level description of the section, its draft status, and other things:


You can see that most of the chapters are First Draft, meaning that I’ve gurgitated out the text, did an editing pass, and it’s ready to make the one-way trip to DocBookland for markup, professional editing, and indexing. A couple are “In Progress”, meaning they’re being worked on but not ready to see the light of day. I can tell at a glance what shape the chapter is in. You can rearrange the document here too. Clicking and dragging the note cards is reflected in the outline view, and hence in your overall body of text.

One of the cool things is the text contents of the note cards. The title of the card matches the title in the Binder view. Simple enough. But you can also have a description, independent from the actual contents of the section. Scrivener gives you a lot of opportunity for out-of-band data. With traditional word processing environments, pretty much everything that’s in the document is part of the flow of text, except maybe things like reviewer’s comments. Scrivener has lots of opportunities for attaching meaningful metadata to sections: add tags, arbitrary keywords, arbitrary long notes and descriptions. Fiction writers can tag scenes with characters, themes, locations, smells, etc. Later on they can do searches to see all the scenes a particular character is in, or what sections concentrate on badger foreshadowing.  I didn’t use much metadata stuff, mainly the note card descriptions and the status.

In addition to the “Draft” area, which has all the text of your document in the little entity files, you can have any number of non-publishing hierarchies of stuff. I do most of my research in VoodooPad – it’s where all the raw information goes as I read technical docs, research on the web, and write test apps. Then I bring it over piecemeal into Scrivener as I suss out how things should be organized, and figure out what needs to be included and what can be left on the floor. Here’s the research part for Instruments:


Each of the texty-looking icons is the equivalent of a text file. You can have whatever text you want there, formatted how you want, embedded images, etc. Kind of like Keynote, these text docs aren’t the leaves of the tree. They’re also the internal nodes. The “Different Kinds of Instruments” text doc actually has three child documents too, each with their own text. I can select “Different Kinds of Templates”, and see its text, along with the children’s text in-line (if I want). There are also images, in this case screenshots, that are part of the “document” hierarchy. As I was writing the chapter, I’d be migrating important information from Voodoo Pad, arranging and rearranging entities so the order of presentation made sense. I wrote a fair amount of the chapter’s prose here. As I took screen shots, I added them as child nodes to the text they would appear in. This way they’d carried along as I rearranged chapters. It’s a very powerful, yet easy to use system.

One odd thing about Scrivener is that it is actually fun to write in. No other text editor feels as responsive as Scriv’s. It’s hard to describe, but typing just feels better than in other apps. The obligatory full-screen mode is nice when you have to concentrate to Get Things Done.  Also, I am a huge fan of the “typewriter” mode. This centers the line being edited in the window. I can have a tall window so I can get lots of context, but when I’m actually typing and editing, the text is in the sweet-spot of my eyeglasses.

Indie developers would should take a good look at Scrivener’s website.  I spent a long time reading the materials, and looking at the demo movies.  They’re all very targeted.  “Here is a cool feature, here’s how it fits in with the rest of the product and here is how you would use it.”  After awhile, I got a very good sense of the how the product worked, and what particular features would make my life easier.  I had zero problems getting Real Work done immediately after download.

So, if you’re into any kind of long-form writing, whether it be novels for NaNoWriMo or technical books, or even the occasional complicated blog post, I recommend you check out Scrivener. It does so much Right that it is a joy to use.

September 6, 2010

Block Retain Cycles

Filed under: amosxp, programming — Mark Dalrymple @ 10:37 pm

So I’ve seen in a couple of places where you can get retain cycles with Objective-C blocks, and then have to do some contortions to get a __block-storage-class self pointer that won’t be auto-retained.

But I couldn’t find a simple example to demonstrate the problem, and I want to verify the problem before it gets cast into dead trees or implanted into student’s minds.

So here is minimal example. First is a typedef for a block pointer, and a simple object that holds on to the block:

// Just a simple block pointer that asks for nothing and gives nothing.
typedef void (^BlockHead)(void);

// The leaky object.
@interface Leakzor : NSObject {
    NSString *string;
    BlockHead blockhead;

// Print |string|.
- (void) funk;

@end // Leakzor

This will leak the object and the block due to the retain cycle:

- (id) init {
    if ((self = [super init])) {
        string = @"snork";

        // |string| is the same as self->string, so |self| is retained.
        blockhead = Block_copy(^{
                NSLog (@"string is %@", string);
    return self;
} // init

If you compile blockcycle with -DRETAIN_CYCLE=1 you won’t see the dealloc NSLog. Why?

blockhead has caused self to be retained. self won’t be released until blockhead is cleaned up in -dealloc. But -dealloc won’t get called because self is still retained by the block. This is a classic retain cycle.

So how to fix it? With these hoops:

        // |blockSelf| is __block scope, so won't be auto-retained
        __block Leakzor *blockSelf = self;
        blockhead = Block_copy(^{
                NSLog (@"string is %@", blockSelf->string);

So now I access string by using the self pointer, but in the shape of a __block-storage-class local variable. This doesn’t have the retain behavior that ordinary variable capture has.

Does this mean that I’m going to be peppering every block that refers to self, directly or indirectly, with this stuff? Nope. But it’s something to keep in mind, especially if you’re making a copy of a block and then dealing with its cleanup in -dealloc (vs some kind of good-bye kiss method).

January 4, 2009

New LoC is here

Filed under: amosxp, Big Nerd Ranch, LoC — Mark Dalrymple @ 6:02 pm

It’s finally seen the light of day. Learn Objective-C on the Mac is currently in dead-trees form, and available at amazon and other fine retailers.

I’m rather proud of the work that Scott Knaster and I have done on this second edition. It is the contents of the first edition from Spiderworks, but with about 100 new pages of goodies, including NSPredicate and Key Value Coding. There’s also a whole new chapter on Xcode tips and tricks.

The book is designed to sit between Dave Mark’s updated Learn C on the Mac and Dave’s and Jeff Lamarche’s most-excellent Beginning iPhone Development (exploding exploring the iPhone SDK). We go into things figuring you’ve met C and programming, so no “for loops are fun! ooh! variables!” kinds of rehashing. Instead we cover what’s been added by Objective-C, as well as some software engineering topics like indirection, object-oriented programming, the Open/Closed principle, and refactoring.

Plus the book is written to be fun. The English language is one of my favorite playthings. But the humor isn’t over the top and in your face. (at least I hope so)

On the AMOSXP front, we’ve added about 100 new pages of material, such as Objective-C 2.0 goodies (including some perversions of NSFastEnumeration), 64-bit programming, FSEvents, Dtrace and instruments, and NSOperation; and have also been removing some of the old and obsolete classic Mac information since it’s not relevant.

Fourteen students at the Big Nerd Ranch‘s Advanced Mac OS X Bootcamp got a first crack at the new material. There is a second bootcamp scheduled for February in Frankfurt. The actual publishing of the next edition (and its ultimate contents) will hinge on Snow Leopard’s schedule. Hopefully MacWorld will give us some schedule insight there.

January 29, 2008

Concurrent Programming with Many Mes

Filed under: amosxp, LNC — Mark Dalrymple @ 10:50 am

I had the pleasure of recording another Late Night Cocoa podcast over at the Mac Developer Network. This time I blabbled about concurrent programming, including some chatting about NSOperation.

If you know something about Cocoa programming, I’d like to encourage you to do a LNC podcast. Scotty is a pleasure to work with.

January 21, 2008

Chunky text in Pages

Filed under: amosxp — Mark Dalrymple @ 6:28 pm

I’ve been using Pages for writing new AMOSXP chapters, and for the most part, it’s a pleasant experience. I’ve just about got the NSOperation chapter put to bed, and was making a PDF to send off to the first round of reviewers, when I noticed the generated PDF output was beyond horrible. Here’s what it looked like on-screen:

Picture 19.png

and here’s what the resulting PDF looked like:

Picture 18.png

Hideous, isn’t it?

Turns out that Pages is honoring the “Turn off text smoothing for font sizes x and smaller” when generating the PDF, and using bitmaps for the smaller font sizes. I have that set to “12 and smaller” because anti-aliasing plus my eye correction conspire to make things difficult to read. Why Pages is using this setting for PDFs is beyond my comprehension (and I hope it’s just a bug – VoodooPad does the RightThing. Filed Radar 5698417). You’d think that PDFs are being made for someone else’s consumption, and so wouldn’t carry along personal preferences like this.

September 29, 2007

Don’t Forget VoodooPad

Filed under: amosxp, programming, Random, work — Mark Dalrymple @ 3:57 pm

With all of the love and attention that Flying Meat’s Acorn is receiving, I figured I would remind folks about VoodooPad.

VoodooPad is a personal Wiki that lets you write stuff and link things around. When it sees words in CamelCapsStyle, it automatically turns it into a link to a new page where you can write more stuff. All pretty standard wiki stuff. It uses the OS X text engine so it has all of the standard word processing features you’ve come to expect, including stuff like tables and lists. This is especially nice because I get a lot of my emacs key bindings along for free. Muscle memory is a wonderful, wonderful thing.

Screen Capture of VoodooPad pro

There are a couple of things I love about VoodooPad : it gets out of my way. I type, I link, I paste in graphics. Gus has obviously paid a lot of attention to the fine details and the app just gets out of my way. It is also very stable. I don’t remember when my last crash was. It just works. Just about every Leopard update makes SnapZ pro freak out and I have to get get new license keys (and then usually something fails on the server side, and takes 20 minutes of dinking around to get a license). Omnigrackle‘s layers get confused and the PDF export dialog has a bug that makes it easy to corrupt your document. regularly crashes. But VoodooPad just keeps on chugging along. Oh, and it’s fast, too.

Some folks I know put everything into a single VoodooPad document and use it to store their life (or at least their brains). I typically have one VoodooPad document per project, which usually fall int into one of three broad categories:

Design Document : I have one where I keep my design notes for the Extreme Cross Stitch Design software I’m working on for the Spousal Overunit. I dump figures from OmniGrackle in there, and use class names as the currency of links. This makes it very easy to capture my thinking about the specifics of individual classes, as well as highlighting the interactions between classes. Sometimes I can go for a month or two between working on the App, so having all this stuff handy and interlinked makes it easy to reload my mental state. My winning IronCoder entry included a VoodooPad design document with all sorts of notes. (The entry was Race Against Time, if you’re really bored)

Data Dump and Organizer : I have another one where I keep all my notes, to-dos, transcriptions, and copies of interesting emails for the next edition of AMOSXP. You can see a screenie for this is over to the right. I blort in anything and everything I think might be interesting for the next edition. As I start chewing up a chapter, I have ready access to stuff to consider for exclusion (and stuff to nuke). Sometimes one topic (say an extension to a favorite object-oriented language) is too big for one chapter, so something like its automated memory management technique would make better sense living in the Memory chapter. So I can easily make a note in MemoryChap to say “go look over InThisSetOfNotes for these aspects of rubbish aggregation that would be interesting to talk about here”

Debugging Aid : For projects where I tend to do more debugging than design, I have a VoodooPad document that keeps my debugging notes. Usually for each non-trivial problem there’s a page with a dialog with myself. “So What’s the Problem Fool? Oh, Google Kipple is crashing when you frobulate the giznat. Does it happen all the time? No, just on the second launch. Maybe it’s the SpicyPonyHead user preference Hrm, could be” The dialog format lets me focus my thoughts by making explicit what the next useful piece of information might be, and it makes for easier reading when I need to revisit a bug or if I have to put it down for awhile and return to it later. The linky nature of a wiki makes it easy to put in different branches of investigation and let me revisit what I originally thought was a dead end, but might actually be the path to figuring out the real problem. Because Cocoa class names are CamelCapStyle, class names in stack trace become links. Ppaste in a stack trace and then link out to a class to jot down some relevant notes.

I’m a fan. Check it out.

September 13, 2007

C Callbacks in ObjC

Filed under: amosxp, irc, programming — Mark Dalrymple @ 11:23 am

It’s interesting to see common subjects come up in the IRC channels. When someone unfamiliar joins and asks the question “how do I put a method into a function pointer?”, 9 times out of 10 they’re actually wanting to use Cocoa with an existing C API that uses callbacks. A much better question would be “I’m using a C API that uses callbacks with Cocoa, how do I make it work?”

The Answer

You can’t use Objective-C methods as callbacks. Stop trying, you’ll just make yourself angrier. You have to bounce off of a regular C function, and use any “userData” or “info” mechanism in your C API to pass a pointer to your object.

So assuming you have a call SetDrawingCallback, which takes a function, but you actually want to draw using your objecty-goodness OblateSphereoid object, you would do something like this:

BWOblateSphereoid *egg = [[BWOblateSphereoid alloc] init];
SetDrawingCallback (drawingContext, /* context that wants to draw */
                    drawEggThunk, /* the function that the context will call */
                    egg);  /* arbitrary userData pointer */

Then in your callback function:

void drawEggThunk (DrawingContext *context, Rect areaToDraw, void *userData)
    BWOblateSphereoid *dealie = (BWOblateSphereoid *)userData;
    [dealie drawAnEggInRect: areaToDraw];
} // drawEggThunk

You are allowed to call Objective-C methods in a C function. You just need to make sure your file is compiled as Objective-C, whether you have a .m extension, or tell Xcode to compile it as Objective-C explicitly. If your callback API doesn’t let you pass in a userData pointer (a rock to hide your data under), you’ll have to put your object into some global location for your C function to find.

If you need to poke inside of the object directly, you can put this function inside of the @implementation block of your class, and then you can access instance variables with the C arrow operator. But that’s kind of naughty, so to preserve your Purity of Essence you should be using method calls on your object. End of Sermon. Here’s the evil:

@implementation OblateSphereoid
void drawEggThunk (DrawingContext *context, Rect areaToDraw, void *userData)
    BWOblateSphereoid *dealie = (BWOblateSphereoid *)userData;
    dealie->_frognatz = [NSColor plaidColor];
    // and more stuff.
} // drawEggThunk

@end // OblateSphereoid


So why can’t you just (somehow) get the address of -drawAnEggInRect: for the BWOblateSphereoid class and pass that for the drawing callback? The answer is a secret. Two of them, in fact.

When you use brackets in Objective-C to send a message to an object, the compiler is actually generating a call to the C function objc_msgSend (or to one of its variants, but let’s keep it simple):

id objc_msgSend(id self, SEL op, ...);

So something like [egg drawAnEggInRect: someRect] turns into:

objc_msgSend (egg, @selector(drawAnEggInRect:), someRect);

Which then calls drawAnEggInRect:, which under the covers boils down to something like this:

void drawAnEggInRect(id self, SEL selector, Rect someRect) ...

self and the selector are passed in as secret hidden parameters, and then any arguments for the method follow them. This is why you can’t just use the address for a method’s code in a C callback API. The library code invoking the callback will be wanting to put its own stuff in the first couple of arguments, which will cause all sorts of nifty explosions when Objective-C starts interpreting those as object pointers and selectors.

August 23, 2007

Book Mania

Filed under: amosxp, programming — Mark Dalrymple @ 11:38 pm

Thanks to Vinoodle for pointing me to Antonio Cangiano’s blog, and A preliminary review of three Cocoa and Objective-C related books., where he has some very kind words for AMOSXP.

One book I like to point folks to, particularly folks who already know how to program and/or already know C (which don’t always necessarily occur at the same time :-), is Andrew Duncan’s Objective-C Pocket Reference If you can find it, that is. I see with horror that it’s currently unavailable via Amazon and Barnes’N’Ignoble.

It’s a mercifully short book, especially compared with the giant C++/Java in a NutCaseShell books, and it hits the important goodies that Objective-C adds. It even talks about the extra syntax relating to Distributed Objects.

I also have to plug Learn Objective-C on the Macintosh (a.k.a. LoC), co-written with Scott Knaster. What many folks don’t know is that Scott’s early Macintosh books in the mid to late 80’s were some of my main inspirations for becoming a professional programmer, and a Mac programmer in particular. I pretty much owe my career, and my current gig at Google, to Scott. I had a chance to meet him at a Big Nerd Ranch course a couple of years ago, discovered he’s a really great guy, and eventually we ended up collaborating on LoC (oh man was that fun). I figured out what we were covering and blazed the main trails, and he made it understandable and fun to read.

If you’re already slinging bits and swizzling IMPs then LoC will be too basic for you. Otherwise, check out the sample chapter and see if it speaks to you. If you’re truly coming up from scratch, you might want to start out with Dave Mark’s Learn C on the Macintosh (LoC is designed to pick up where LearnC leaves off, and Dave was the editor for LoC), and there’s also Stephen Kochan’s Programming in Objective-C, which Antonio also reviews. (I liked it, but I’m a pretty nerdy bookworm.)

August 17, 2007

The tools behind the book

Filed under: amosxp — Mark Dalrymple @ 9:10 pm

A discussion on my Local Linux User’s Group‘s mailing list talks about Open Source tools used to write books.For the curious and/or terminally bored, here are the tools that were used to make AMOSXP:

Along with makefiles and perl scripts to hold everything together. It was a real PITA to get build and configured. But once that horror was dealt with, it’s a fun toolchain.

Blog at