Scott Stevenson (above) has posted videos from the May CocoaHeads. They're available via a torrent as well. The main topic was a rapid introduction to Cocoa.

CocoaHeads Silicon Valley continues to draw good attendance. I'm sure that the WWDC meeting will be packed just like it was last year.

Tags: CocoaHeads, Video, Xcode, Apple, WWDC

There's a huge debate going on right now on Apple's Cocoa list (archives on Cocoabuilder) about the suitability of the current developer documentation for Cocoa and Objective-C.

Today I threw my assessment into the ring with all the others. See below:

The documentation debate is actually several orthogonal debates that regularly get intermingled:

* What should the purpose of the documentation be?

* How should it achieve those goals?

* Who should be responsible for it?

The answers to these questions used to be easy because of the scale of the problem: small. As Apple grows, as its software base grows, as its customer base grows, and as its developer community grows, so does the diversity of all of those and difficulties and vocal minorities with those difficulties appear.

An area where Apple has proved itself to be a master in its *products* is that of managing expectations. Only by managing expectations is it possible to consistently satisfy and delight customers. But we're not debating products here, we're debating *developer documentation* and that's not a product. Or maybe it is? I argue that it is not because if it were then Apple would be managing it like one and is clearly not. If it were, then the three questions above would have answers and we would all know and understand them. It is notable that for the iPhone SDK announcement there was a live public demo of Apple's developer tools -- a milestone event -- so maybe the path to the productization of the documentation is coming.

To add fuel to the multiple fires here:
 
Erik Buck wrote:

"Cocoa is the most consistent, elegant, and productive software development technology I have ever used, and I have used a lot.  Cocoa uses key metaphors and design patterns ubiquitously.  If the programmer is either unaware of the metaphors or  does not see their utility, it will be difficult to use Cocoa.  If a programmer fails to grasp a particular pattern, the whole framework may be incomprehensible because the pattern is most likely used throughout."

Many of those with difficulties know and understand this. It's the best thing since sliced bread and they want to learn, badly. They quickly find that the Cocoa way is not the same as the Java or C way, and while there are a small number who will simply complain that it is unfamiliar and do nothing about it, the majority just see it as another thing they need to grok. Programmers have one thing in common: they want to be productive. Those learning ObjC/Cocoa are doing it because they want to be productive and they believe that mastery will make them greatly productive.

"The attributes of Cocoa that make it so consistent and elegant are exactly the same attributes that I think newbies are complaining about.  The newbie complains that the reference documentation mentions delegates or tags or data sources or the responder chain or key value coding or bindings or targets or actions etc. without defining them".

But the documentation actually *defines* them very well. What the documentation does not do is to justify the existence of these things, explain the problems that they solve, put them into context, relate them to the user's situation, reassure the reader how much they need to know right now to get to the next step, etc. It does all of these things *in places* and to different degrees, but not consistently and not enough. The environment is hostile to learning.

"This is exactly like  a newbie complaining that clicking and dragging and selecting and double clicking are used throughout a GUI but not explained in the documentation for every application.  Once the GUI metaphors are internalized, it is unnecessary at best and annoying at worst to keep encountering mouse based selection explained in every user's guide.  The consistent application of the metaphors makes the GUI easy to use.  The consistent use of metaphors makes Cocoa easy to program. BUT YOU MUST UNDERSTAND THE METAPHORS FIRST in both cases."

And this is precisely why there used to be sections in computer manuals on mouse usage, hierarchical file systems, etc., all unfamiliar concepts to many of the users. But there are *no such sections* in Apple's docs. Should there be?

No really, I can't find them. Here I am in Xcode's docs and I'm typing in Concepts, Conceptual into the search box, and any way I try it I don't find any conceptual docs except Core Foundation Design Concepts (now three years old). And if I go to the developer site and find my way to http://developer.apple.com/documentation/Cocoa/, there is nothing labeled "conceptual". Let's try the pop-up on that page: Jump To: No concepts.

But the idea of conceptual documents *really is* there. The document Introduction to Cocoa Bindings Programming Topics has the following path: http://developer.apple.com/documentation/Cocoa/Conceptual/CocoaBindings/CocoaBindings.html. It's in the *Conceptual* folder so I know that conceptual documents exist here as a concept at least. Now show me all the conceptual docs in one place so I can learn the concepts!

Now *I* know that the Guides fill a conceptual role, and Getting Started With Cocoa tells me to go see the Guides for conceptual information. But when I actually go there practically salivating with anticipation, it's organized by *Topic*, not by Concept. Show me the concepts!

Let's try a global text search at the developer site: 8600 documents show up, and I meet Core Foundation documents before I meet Cocoa. "Cocoa Concepts" does somewhat better with 1500 documents, but still. Where do I start? How about Core Data, that shows up near the front and sounds pretty conceptual....

Am I looking in the wrong place? For the wrong thing? How would I ever know if I'm starting out?

Perception is everything. If the newbie perceives that it's all screwed up then it *really is*. It doesn't matter if *you* learned Cocoa from reading the backs of cereal boxes. *You* are not the typical Cocoa learner. And this is key and why the docs need fixing: Almost nobody here is a typical Cocoa learner, because at least 90% of the typical Cocoa learners have not yet even arrived in Cocoaland. 

On May 18, 2008, at 4:33 AM, Julius Guzy wrote:

"The very good , interesting and informative debate in this list concerning the accessibility of the programming environment to new users has it seems to me incresingly polarised between those who think the documentation more or less adequate and those like me who for whatever reason, have great difficulties making use of the facilities."

Here is an example of the difficulty. Go to the Cocoa section of the Core Reference Library. Click on Fundamentals (Essential information for developers using Objective-C) and select Memory Management Programming Guide. I'm playing the part of a good newbie here -- clicking on everything that claims it is fundamental, essential, and core to the whole thing. By being here I am told that memory management is fundamental, essential, and core, and the document reinforces that. The first thing it says is:

"Memory management, especially as it concerns Objective-C programs, is an important subject. Some of the more common problems encountered by novice application developers derive from poor memory management. Cocoa provides mechanisms and a policy to assist you in the proper creation, retention, and disposal of objects." 

Wonderful! I am in the right place. The docs are doing their job. But in the second section I find that:

"Cocoa does not use garbage collection. You must do your own memory management through reference counting."

Really? I'm sure that garbage collection was in here somewhere, that was one of the reasons I wanted to learn Cocoa all of a sudden. And then later on, there is a whole section on Core Foundation memory management, talk of retain cycles, NIB files, data sources, weak references, and the like. Whaaaaaaa?? If this is the fundamental stuff, what do the tricky bits look like?

The individual developer documents are of very high quality, and this particular document is no exception. It is well-structured, complete, consistent, has many references to other documents, stresses the importance of important things, shows simple examples, describes common errors, has good readable English, etc. Some of the developer docs I have read are truly exceptional, describing very difficult material very precisely and very clearly, so it's not a lack of writing skill or the ability to explain complex things.

So what is wrong?

1. This document that I believe to be fundamental, essential, core, and important *does not stand on its own* and so robs me of understanding.

2. It is at least five times too long and contains material that while fundamental, is not fundamental to *my learning as a newbie*.

3. It has not been designed as a learning tool. If it had then it would be goal-oriented and as a learner I would be able to measure achievement by reaching that goal. I would then have confidence that my task was complete and would tackle the next fundamental item.

4. It has not met my expectations

The last point is the most important one. For whatever reason I expected to be able to learn from the documentation and it was only when I tried to do that and failed were my expectations dashed. *As a product* the documentation fails for this one fundamental reason. If I were here because I had somehow missed the huge Learn Cocoa Here banner on the developer site and clicked in the wrong place, then it would be my fault (or I had continued past the banner that told me not to learn here). But there is no such banner and no such material, and so I have every reason to believe that I can learn here.

While the documents themselves are very good, I believe that the architectural problem is that the *documentation* is not. That is, as a body of work, it is on the verge of no longer meeting the needs of developers. That's because the nature of developers themselves has changed, and the current documentation organization does not scale. Apple's own product success (iPhone!) and ease of use sets a very high expectation bar for new developers too.

It is also worth noting that many (most?) younger developers expect (demand?) an agile approach to learning new languages, environments, and concepts. Maybe Cocoa is not like that and can never be like that, but this is the expectation that Apple faces. A Google search for "agile cocoa" yields no Agile books (but at least does lead to Fraser Speirs).

"I think this debate relates to the same concerns and battles we had, and in many cases are still having about computer usability, namely the effective design of human-computer interfaces, aka HCI.

It is ironic that we are having this debate within an Apple programmer's mailing list. Apple has been celebrated for the usability of its machines and long may it continue to be so. However, Apple has been less celebrated for the humanity of its programming interface having, in my experience of Macs from the Lisa onwards, seemingly taken the attitude that its programmers were hobbyists, geeks essentially, who because of their enthusiasm would successfully negociate their way into the machine's innards. That said, the 9 tomes of "Inside the Macintosh" documentation of the programmer's workshop were pretty good once you got into them but there was a lot less to get into then than there is today"

It's a scaling problem. That fundamental memory management document above covers a lot of ground out of necessity  (in order to be complete in the face of scaling) but in doing so covers too much ground (in the face of scaling of readership and hence the diversity of reader backgrounds).

"This question of volume of documentation and system size and complexity is significant to our debate. It is pertinent to quote what one of the great programming pioneers, Dijkstra said about PL/1: That it " must be like flying a plane with 7,000 buttons, switches, and handles to manipulate in the cockpit. I absolutely fail to see how we can keep our growing programs firmly within our intellectual grip when by its sheer baroqueness the programming language - our basic tool, mind you! - already escapes our intellectual control". ("Humble Programmer", see Prgramming Methodology 1978).

Well I think that the sheer size and complexity of Cocoa et al comes close to being an aeroplane cockpit and one which we are largely expected to learn to use from engineering manuals essentially concerned with listing the identity, composition and location of components,(not to mention the various incarnations of Xcode and Interface Builder). I am not saying that tremendous pains have not been taken to create a robust coherent system nor to document it. There have. Also there are many who have succeeded in mastering the system. Some will have done so through having grown up with it from early days, others will have had the fortune to attend (expensive) traning courses, and others still will have done so through dint of talent, perspicacity and hours of hard work. So mastery is possible. But I am not stupid nor a shirker nor a complete novice and I expect that the same can be said for most people who have had and are continuing to have horrendous dificulties in getting to use the system. It is clear that the programing interface to the Mac has serious usability issues."

It's not the programming interface that has difficulty. It really is extremely good and very well thought out. Every time I do something the "right" way I end up with less code and understand a little more of how smart the people were who created all this in the first place.

It just doesn't look so good to those who don't understand why it is like it is. There are some similar arguments to this one about the interface to Blender, the 3D modeling and animation application. It's hell to start with (three button mouse? you must be kidding...), but much later you realize why it all makes sense because the enormous complexity you would otherwise face at that later point is so much more manageable than with other apps. Experienced Blender users are amazingly productive *and* they can keep up with the rapid scaling of the platform because of its conceptual underpinnings. The Blender docs are another matter though...

"I cannot help touting one recent example. To specify the outlets etc between a class definition and Interface Builder on Leopard we are told to type the name of the class into a field and that thereafter IB will make the appropriate links with Xcode. It took me ten minutes of doing it this way and that before I realised that IB would only make the connections AFTER one had typed in the class name AND saved IB! We know from HCI research that it is little things like this which most frequently cause users to give up and never touch the equipment again."

Exactly. Conceptually, saving triggers the connection and makes the magic happen. But how is that concept learned? Where is the metaphor? Why is saving even needed?

"Now, of course, as programmers we are well used to wasting hours hacking through the underbrush to discover that to switch on the machine we need to hold down Alt-Escape with the right hand whilst depressing a button round the back of the machine with the left. (That was how in the 70s one turned on some of the PCs at Leicester Poly!). But what a waste of time and effort and how demoralising and off-putting to anyone but the most obstinate programmer. I deferred having a go at Cocoa for about three or four years because I knew it would be a struggle and these last five months or is it six have been horrorshow.Let me state two principal facts.
1. Designing good user interfaces is hard.
2. Designing good user interfaces is expensive.

It is hard because every human being is an individual,
because there is seemingly a lot to learn
and because there are limits to the complexity we can handle.
It is expensive because the design of good HCI is primarily an empirical activity centered on user testing"

Perception is everything! 

We have right here the results of some user testing and yet those results are not being accepted as valid. Why is that?

"The question is then whether we and possibly apple should do anything about it"

Let's look at the issues again, partition them the way I think they should be, and throw in some answers:

* What should the purpose of the documentation be?

To hook beginners, to teach learners, and to support experts. These three different goals require mutually exclusive techniques and tools, but currently there appears to only be one big classroom and one textbook at Cocoa School.

* How should it achieve those goals?

Reward beginners with their concrete understanding; reward learners with their concrete code; reward experts with their concrete profit.

* Who should be responsible for it?

Ultimately it must be Apple because they control the code. They don't have to write the material themselves, but they must find a way make it possible for the material to exist and be found. There is no "Apple Press". There is little to no investment in a writing community that could fill in the gaps. There is no structure into which additional material can fit in a rational fashion, although there is all sorts of material out there that we stumble across. 

Jason Stephenson wrote:

"I also don't find any great difficulty in using Apple's documentation. The conceptual documents cover the concepts, and the reference documentation serves as a reference. No, I don't think you should learn to use Cocoa just from the conceptual documents, but I'm sure it is possible.

The simple fact of the matter is that documentation, just like a GUI, cannot be all things to all people. Programmers and those interested in programming are a particularly eclectic bunch. We each come at Cocoa for the first time with different experience, different reference points, and different expectations. One set of documentation cannot be expected to handle all of the possible permutations of programmer knowledge and experience. For this reason, other books exist written by third parties to cover those gaps or target different audiences."

Agreed. So what about third party books? Surely everyone is expected to go buy a book and use that. Well, not everyone does these days, since the web has taken over much of the world's publishing. But let's give the developer docs a chance and see what is recommended. Go to Getting Started With Cocoa at http://developer.apple.com/referencelibrary/GettingStarted/GS_Cocoa/ and look at Start Here. There surely cannot possibly be a better place to start! There are two book links:

http://www.oreilly.com/catalog/9780596003012/ leads me to a book published five years ago.

http://www.oreilly.com/catalog/9780596002350/ leads me to another book published five years ago.

And the other books on the page are of the same vintage.

You see the disconnect -- we all know that this is not how the great Cocoa books are found, yet here it is in the docs. Apple's documentation is not integrating well with other resources, and worse, maintenance appears to be falling behind somewhat. This is not a tenable position. Just as a city gets run down area by area, not noticed or lived in by those who could foster change, documentation, especially documentation on this scale fails in the same way with the new users in the slums. 

Why this situation?

Jason Stephenson also wrote:

"In summary, I think it is a problem of all programming documentation and programming interface regardless of the platform or language, and I don't really see a way for a single vendor to resolve the issue, not do I think they really should"

But since Apple is the de facto owner of Objective-C and the actual owner of Cocoa, there is no alternative! 

The allocated resources at Apple are just not sufficient for the current task. It's not that the problems are not known or fretted about, it's a matter of priority. We and everyone else can debate and complain as much as we like, but no lasting changes will occur until this particular user interface is viewed on a par with the consumer user interface and dealt the resources commensurate with its importance.

Tags: Apple, Cocoa, Xcode, Documentation, Writing, Objective-C

Two videos and slides of the April Cocoaheads meeting is now available online. For details, see Scott Stevenson's blog entry. There's a total of some 750MB of material.

It featured Scott (seen above) on user interface design, and Joar (below) digging into the debugger.

I'm in the audience asking intelligent questions.

Tags: Cocoa, CocoaHeads, Mac OS X, Movies, Xcode

Alex Cone wins the prize for the geekiest name tag at the first Silicon Valley iPhone Developer meeting put together by Tim Burks.

Chi-Hua Chien of KPCB talked about the iFund, KPCB's $100 million fund for investing in new iPhone applications. The meeting was well-attended: probably close to 80 people there.

Tags: iPhone, Xcode

I managed to code myself into a corner writing my Mac application. IKImageBrowserView has some quirks and when I tried to reorganize the structure of my code, I couldn't get it to work at all. The changes were combined with Interface Builder alterations as well, so it was complicated.

I have an alternate approach, but I have to undo the changes I made. Subversion to the rescue. I have a subversion repository set up and so I can revert to a previous version. But how? The subversion functionality in XCode is very limited: it's really only any good for checking in new versions and looking at history. There is no way to see the structure of past versions and no way to revert any more than single files.

The answer was to tag the current version by copying it to the tags subversion folder and then check out the older version. I did all of that with snvx. It's a simple but functional GUI subversion client.

My subversion repository has moved from its old location that I set up with Tiger. I had hoped to be able to access it from my laptop over AFP, but locking does not work. So I moved it to an HTTP server-based repository. There are plenty of places on the web that detail how to set it up with Leopard, and it was simple to do. Next I need to figure out how to do ssh tunneling and I'll have a remote access solution.

Tags: Subversion, Xcode, Programming, Dead Ends

James Duncan Davidson has posted an interesting article about his meeting with Apple's Aperture team. He told them what irked him about Aperture as a photographer and they went off and fixed it. But how did they fix it?

I've looked a little at the internals of Aperture 2.0 and there are some striking differences between the two. It looks as if the whole core of the application has been rewritten.

Here is one thing I found. That diagram below is the data model for Aperture 1.5. The boxes represent information stored about things like versions, albums, vaults, adjustments etc., all the things that are carefully managed by Aperture and kept in a consistent state, all the things that are needed to display and manipulate images through the interface:

What matters is the number of lines in the diagram. I reckon there are about twenty. Each one is a relationship between the data in the boxes and many lines means much complexity and lots of work to keep things in order. And the impact of complexity grows very quickly as the number of items increases.

Now have a look at the data model for Aperture 2.0:

Still plenty of boxes, several more in fact, but hardly any lines. And only two are actual relationships, the two in the center representing inheritance instead. This means that Apple has eradicated the complexity inherent in the data model and moved it elsewhere, clearly to something faster.

This is at least partly why Aperture 2.0 is so much faster than Aperture 1.5. The other benefit of removing the complexity is that reliability should increase, so I'm hoping for a more stable, less buggy application.

For anyone wondering how I got hold of the data models for Aperture; it was easy. I just decompiled the .mom file in the application with Xcode.

Tags: Aperture, Cocoa, Core Data, Xcode

There are many changes in Cocoa beyond the obvious XCode enhancements and brand new Interface Builder. I have had scant time to delve into all of this, but Matt Gemmell has, and he has posted a long list of improvements that have been provided for us behind the scenes.

Behind the scenes views must be his forte because his about page reveals every last detail about him, down to the color of his underwear (well almost -- but it does mention socks).

Tags: Cocoa, Leopard, Socks, Xcode, Mac OS X

Leaves as artwork clearly represent the current frontier of web design. Now we have Versions, available as a beta that promises to make subversion easy to use on the Mac. That would be very nice since I use an assortment of tools right now and it is not a very satisfactory arrangement.

Linus argues that none of this is worth anything (the video is long but worth the time -- much clearer than reading the text of the talk). The comments are all over the map. That's a good sign that he is right. If the experience of users is so scattered that no-one can even agree what the problem is, then something is seriously wrong. What exists today is barely usable. It just doesn't feel that way because having anything is so much better than having nothing at all.

Tags: Subversion, Leaves, Xcode

The logging I have been doing is very primitive. I call NSLog() to see what I want to see and have to manually insert and remove these calls (or mess with comments) to control what is going on. It's time for something better. Looking around, I found a handy logging class at Borkware that does much of what I want called MLog.

It implements a logging system that includes the line number and source file name with each message. This is very useful for understanding what is happening when reading the logs. The change I made to that code was to add control over the logging level.

Here are the definitions for my version of MLog.h. I implement seven levels and add the ability to revert to standard NSLog() calls, or to remove all the logging code completely:

Macros take care of inserting the correct code and extracting the file name and line number from the preprocessor. The class implements two class methods: one for actually logging messages, and one for setting the current log level. The idea of the level control is that the minimum log level can be set either by an environment variable or by code and only messages logged at that level or above will be shown.

The Implementation includes a static variable that holds the current log level:

Initialization is done in the class initializer:

It reads the environment variable MLogMinLevel and uses that to set the initial level. The logging code compares the logging level passed to the method with the current level and ignores those below the minimum:

The level setter code is very simple:

To use the logging, I add lines like this to my code:

and it provides messages that look like this that include the level, the file name and the line number:

Since I provide logging control with an environment variable, I can quite easily create build configurations that behave differently. If I go to the Project menu and select Edit Project Settings I can duplicate the current Debug and Release configurations and make two new ones:

Clicking on on the Build tab lets me set these up:

I edit the preprocessor macros to include the symbols I need to control the logging system. The Release No Logging configuration sets __BTREMOVE-LOGGING, for instance. Once set up I can change the current configuration I want to build and run from the main XCode window just by selecting it:

For this to fully work I edit the custom scripts I added to copy the executable and run Aperture, since the build names have changed and there are more of them.

The other parts of this series can be found via the Cocoa page.

Tags: Aperture, Plug-ins, Cocoa, Random Wok, Xcode, Logging

Random Wok is only being compiled for Intel right now. I need a universal binary so that it will run on the PowerPC architecture as well. This is easy to change. I select the Random Wok target:

Then click on the Info button, and under the Architectures tab, select what I need:

That's all there is to it. Everything happens behind the scenes.

The other parts of this series can be found via the Cocoa page.

Tags: Aperture, Plug-ins, Random Wok, Cocoa, Xcode, Universal Binary

To use my Random Wok project I have to check it out. While the files are in the database they are inaccessible to normal file operations. I will do the check out in svnX.

I'm going to check out all the files in the trunk virtual folder to a new folder called Random Wok in my Documents/Progging/Working folder. First I create that new folder. Then in svnX I select the trunk virtual folder in the browser at the bottom click on the svn checkout button and select Working/Random Wok as the folder to check out to. svnX creates the folder for me and fills it with the files:

svnX has a browser built in for looking at working copies. Opening that shows me the working version I just checked out and lets me give it a more descriptive name:

Double-clikcing on the line shows me a browser that I can use to see the file status:

Now I can get back into XCode. I double click to open the XCode project that was checked out and set it up to use subversion. From the SCM menu I select Configure SCM... and set it up like this:

I change the build location and the location for intermediate files, and enable and select the SCM. I also found it necessary to clicked on Rebuild Code Sense Index for XCode to have the data it needs about my source files. To fully set up the build destination I select the target and change the Build Products Path for all configurations to be that Random Wok Folder:

Now the SCM tab for my project looks like this, showing the initial check-in:

Now I can enable the SCM status display by selecting the Random Wok project icon at the top of the XCode project list and control-clicking on the column header:

Now if I edit a file and save it I get a status change, M, showing modified:

Also shows up in the SCM smart folder on left:

Another thing I need to do is to tell snv that the pbxuser files are binary. This will prevent svn trying to merge them. To do that I go back into the terminal:

How does svn know where the repository is? There is a hidden folder called .svn in the checked out folder. In fact there are hidden .svn folders in all the folders.

Lastly I commit my updated version to the repository. I select all the files to update and from the menu use CMS > Commit Changes, and fill in the commit message:

With the files checked out I can compile and use my project just as I did before I used subversion. Each time I get to a good stopping point, I check in the files.

Eventually I will have a version that I want to release. And that means using svnX again.

The other parts of this series can be found via the Cocoa page.

Tags: Subversion, Xcode, Random Wok, Checking Out

For a long time I have wanted to implement a version control system. The attraction is being able to gain control over my code without simply making duplicates of the project folders. In particular I want to be able to fork and merge different code bases and roll back to working versions. As soon as I involve anyone else in the development process (even testers), it is no longer just me and all this becomes a necessity.

So I am going to install subversion and move my active projects over to it. I have been reading up on subversion for a while on and off, and think that I understand it well enough to implement it and blog it. For the record I'm using XCode 2.4.1, subversion 1.4.3, Mac OS X 10.4.8. Since the interaction among these changes, bugs get fixed, and features get added, not all of this article will stand the test of time.

I'm going to concern myself with just a local repository. I don't need remote access yet, so that will do. This decision means that I don't have to deal with Apache, WebDAV, and a host of other issues that make the set up complex.

A significant cause of confusion is the number of folder hierarchies that have to be understood and managed in the setting up and running of subversion. So to make what I am doing crystal clear, I have some diagrams to illustrate and am using color to differentiate the parts.

I have to work with three different folder hierarchies, so I better get organized.

The first hierarchy is my current project, Random Wok. Its project folder is called Random Wok and its path is Documents/Progging/Cocoa/Aperture/. Inside Random Wok is the XCode project file, the Build folder, and all the source files and resources. Once I have put the project into my repository I will mothball the Random Wok folder. Currently I create new versions by duplicating the Random Wok folder and numbering them. These files and folders are yellow:

The second hierarchy is a new one. To use subversion I will put my code into a folder called trunk that lives inside a virtual folder hierarchy inside subversion repository. That repository (implemented inside a folder) will itself be one of a number, all organized into a real folder hierarchy on my hard drive. As per the subversion documentation, I will also have a branches folder and a releases folder at the same level as the trunk folder. So my first step is to create a folder Documents/Progging/Repositories on my hard drive. That is the real folder that will hold all my repositories. The first one will be called Random Wok Repository and will hold one project. These files and folders will be red.

The third hierarchy I have to concern myself with is that of the checked-out code. I will be checking my code out of the repository to this new location, building and debugging it, and finally checking it back in again when I am happy with the result. If I want I can then delete the code, because it's all in the repository. I create a folder called Working in Documents/Progging and another called Builds. Working is where I will check the source out to and will be green. Builds is where I will have all the Build folders live. I want to be able to keep the builds separate from the code. Inside Builds I create a folder called Random Wok. Inside that is where the builds and temporary files will be kept. The Build files and folders will be blue.

Now I need a copy of subversion. Subversion is actually a collection of utilities, svn and svnadmin being the two I will use the most. I download a prebuilt binary from Coding Monkeys and run the installer. That puts the binaries into /usr/local/bin:

To make using these simpler I set the PATH variable in the current tcsh shell invocation to /usr/local/bin with setenv by typing setenv PATH /usr/local/bin.

Next I need to run svnadmin to create my first repository:

And there it is:

Now I run svn once so it will create a folder called .subversion in my home directory:

Much more information follows that. In the .subversion folder is a config file. I edit this using TextWrangler with File > Open Hidden... and selecting Enable: All Files. In the [miscellany] section I modify the list of global-ignores so that it looks like this (it's actually all on one line):

The modifications make subversion ignore some extra XCode files that I don't care about. I don't include the *.pbxuser files as some people do. That is because those per-user values include the custom executable settings that I need to launch Aperture. Here is the hierarchy so far:

Next I need to set up the repository and import a project.

The other parts of this series can be found via the Cocoa page.

Tags: Subversion, Cocoa, Xcode, Random Wok

Writing Random Wok and other code is always a very punctuated experience. I decide what to implement next, then read and take notes, then figure out what I think I need to do, then write the code, then debug, then blog. Sometimes a lot of time is spent during the reading and figuring out stages as I try to understand either how something is done, or, knowing how it is done, trying to understand how to do it that way in my code.

I go to several offline and online resources to get my curiosity satisfied, my brain overloaded, and my questions answered. Here is a short list of where I go, in order of attack:

1. XCode's Built-in Help and Documentation

My first stop is XCode, Apple's IDE for Cocoa development. XCode has a great deal of information built in: more than a gigabyte of Reference Library, in fact. Access to it all is via XCode's Help menu:

The documentation for XCode itself is found via the XCode Help item. The full developer reference library opens in a viewing window via Documentation:

The documentation window has two modes of searching. If you don't know how these work you will not find things and be very confused. Access the modes by clicking on the magnifying glass:

API search is immediate and needs no carriage return. The window below the search box shows the matches in order of fit. Click on one and I have the document in the lower pane. Double click and it opens in a separate window.

Full-Text Search is not immediate. I must press carriage return for anything to happen. And then the scope of the search is controlled by the selection in the library browser on the left:

My search for NSNull will only be carried out for documentation on Carbon in this case. I have to leave the Reference Library line at the top selected if I want to see all the documents (as I normally do).

The help menu also has two search items that work on selected text. Find selected text in documentation and Find selected text in API reference. An option double click on a word also takes me to Find selected text in API reference. I use this all the time.

Another very handy shortcut is to command double click on a word. That takes me to the definition in the code. This can be very useful because the context and comments in the code can often tell more than the documentation:

I set the languages that are searched via the Configure Options button on the toolbar:

I don't do C++ or Java and this prevents anything about them from showing up. Updates come out periodically. I have auto-checking enabled in the preferences:

So that I get update notifications:

And when a new set of documentation is available, 250 MB or so later, I have it.

Finally, I have access to the Man pages at the bottom of XCode's Help menu. I don't type "man" into a terminal: it is all there in the XCode documentation package.

2. Spotlight

The next place I go is Spotlight. I have all of the developer material indexed so spotlight will locate example code, saved web pages, and all kinds of other documents on my hard drive.

3. Cocoadev

Then I go to the web. Cocoadev is a WikiWikiWeb site containing a huge amount of user-contributed advice, code, explanations, links, and other material. It is easy to search, and you can contribute your own comments.

4. Cocoabuilder

Cocoabuilder is an archive of all of the postings to the Apple XCode, Cocoa, and Macosxdev mailing lists. There is a lot of Apple input on there. You can't post here. To post questions, sign up for the appropriate mailing lists at http://lists.apple.com/.

5. Borkware Quickies

Borkware and its associated Quickies page is a great place to find some of more useful and less documented ways of doing things. It's the creation of Mark Dalrymple, author of several Unix and Mac programming books and teacher at the Big Nerd Ranch.

6. Google

Finally, I Google what I am looking for. That will catch all kinds of things, including hits on the core foundation code, and open source efforts to duplicate parts of the Mac OS.

Tags: Cocoa, Resources, Xcode, Documentation

The user interface for the plugin is a single window. It's a combination of elements put there by Aperture and elements put there by the plugin. So far I have not defined an interface or hooked it up, so there has been nothing to see when the plugin is used except the Aperture elements.

In XCode the resources folder holds the user interface files:

And it is the nib file that describes the interface and contains instances of the objects it uses. Double-clicking on the nib file opens Interface Builder and shows the current Settings View:

I can remove that message, resize the window and add whatever I need to that view to implement the user controls. After some dragging and dropping, and more dragging, and more dragging, I came up with this:

It's not 100% there, but is good enough to get me to the next stage. The string format pop-up is populated with the four ways of creating the random string, but the length pop-up that follows is not. That will need to be filled dynamically by code depending on which choice of format is made.

It took me a little while to figure out how to add new items to a pop-up menu. Either drag a new one (called "Item") from the menu palette, or much more easily, just option drag an existing one.

Some of the interface elements will be disabled when they are not in use. For instance there is no letter case option if Numeric is chosen, so that will go gray. And if Salt is not selected then the Generate button and the text field will be gray and disabled.

The Example file name at the bottom will change dynamically as the user selects and types so they can see an example of the format. It will include the prefix and postfix strings in their proper positions and the random string in the middle.

I added the None strings in the text fields as placeholders in Interface Builder via the Attributes pane of the Inspector. They will appear whenever nothing is present in the field.

The next step is to join the user interface elements to the code and make them do something useful.

The other parts of this series can be found via the Cocoa page.

Tags: Aperture, Plug-ins, Cocoa, Random Wok, Interface, Xcode