The problem with the current version of Apple's document is that it attempts to cover the new kind of Help book that works only in Snow Leopard, as well as the old kind of Help book that works in Leopard and Tiger as well as Snow Leopard. However, from section to section and even sentence to sentence it doesn't explain which kind of Help book it is talking about. You therefore cannot create a valid, working Help book by reading the Apple document alone.
For example, the folder structure of an application bundle that you reproduced in your post is for the new kind of Help book that works only on Snow Leopard. The new kind of Help book is a full-scale bundle of its own, with its own Contents folder, Resources folder, Info-plist file, and so on. In the Finder, it belongs at the root level of your application bundle's Resources folder. This is a plus for developers, because it allows them to manage their Help books completely separately from the Xcode project until its done, when it can easily be added to the Xcode project with a simple menu command (Add > Existing Files, or something like that). For example, with new-style Help books, developers can put all of their language-specific localization folders (English.lproj, etc.) in the one Help book, which they can then send out to localization contractors as a single folder. To create a Help book the old way, that works on Leopard and older as well as Snow Leopard, you have to put a non-bundled Help folder in your application bundle's English.lproj folder, another non-bundled Help folder in the German language .lproj folder, and so on, scattering the language-specific Help folders all over your application bundle's Resources folder in separate language-specific folders. So if your application is supposed to run on Leopard or older as well as Snow Leopard, do it the way Matt Neuburg's movie does it, and read Apple's document with a grain of salt. The direct URL for the movie is <http://www.apeth.com/writersua/implementAppleHelp.mov>. As far as I know, the only writeup available at this time that specifically addresses the new Snow Leopard Help book format is Recipe 11 of my new book, "Cocoa Recipes for Mac OS X: The Vermont Recipes," (second ed., Peachpit, 2010), which devotes about 35 pages to the topic. At the end of that Recipe, I also show how to convert a new-style Help book to an old-style Help book. There are some internal differences as well as the structural differences I mentioned above. Apart from all that, I think you have misunderstood the role of the Groups & Files pane in an Xcode project window. The structure of groups (they aren't really folders, although that's what they look like) and files in the project window is for the most part a matter of convenience to help you keep your project conceptually organized within Xcode. It does not necessarily (and usually does not) mirror the folder structure on disk. On disk, almost all of the files in your project are at the root level of your project folder. The major exception is language-specific files and folders, which go in their own language-specific folders in the project folder in the Finder. For old-style Help books, you would create a Surfwriter Help folder inside the English.lproj subfolder in your project folder, and you would put all your English Help pages and subfolders, and the index file that is generated by Help Indexer, inside that English-language Surfwriter Help folder. You would put a German-language Help folder inside the German.lproj (de.lproj?) folder with its own help pages, subfolders, and index file, and so on. For new-style Help books, the Finder folder structure is different. You would put a Surfwriter Help folder at the root level of your project folder on disk, and you would make it a bundle all by itself by giving it its own Contents folder, Resources subfolder, Info.plist file, individual language-specific .lproj folders, and so on. When writing your Help file text, you typically would not use Xcode, although it does have a perfectly good text editor in which you can write raw HTML by hand if you like. But it's easier to write HTML by hand using BBEdit or TextWrangler, or any other text editor that understands HTML. And if you don't want to write raw HTML in a text editor, follow Matt's advice and use iWeb or a graphical Web page editor. Either way, you might find it a little less confusing to work out of the Help book in the Finder, not the Help book in the Groups & Files pane. Even when not using an outside localization contractor, I find it easier to keep my Help book development completely separate from the Xcode project until the end. However, you can do it out of the Groups & Files pane if you like, because the internal structure of each language-specific Help book in the Groups & Files pane should mirror its structure in the Finder, notwithstanding what I said above about the differences between the Groups & Files pane and the Finder folders. That's because (and this is crucially important) when you "Add" the Help folder to your Xcode project, you must be sure to select the radio button in the sheet that tells you to "Create Folder References for any added folders" in order to preserve the Help Book's internal folder structure when you bring it into Xcode. Is that clear? :) On May 29, 2010, at 12:29 AM, Shane wrote: > I'm trying to create a help book for my app using the "Apple Help > Programming Guide", which is not easy for me to follow -- Bill Cheeseman - [email protected] _______________________________________________ Cocoa-dev mailing list ([email protected]) Please do not post admin requests or moderator comments to the list. Contact the moderators at cocoa-dev-admins(at)lists.apple.com Help/Unsubscribe/Update your Subscription: http://lists.apple.com/mailman/options/cocoa-dev/archive%40mail-archive.com This email sent to [email protected]
