CSS, pronounced "cuss"

I am currently spending most of my time writing the Help Book, the built-in manual for how to use Solitaire Till Dawn.

Help Books are a collection of pages, all written (like a Web page) in HTML. Apple's Help Viewer is basically a sort of customized Web browser. Pages written for a Help Book can also be viewed in any handy Web browser, and in fact that's handy for debugging.

The Help Book for the last version of Solitaire Till Dawn was mostly written in 2000, a good 13 years ago now. I wrote very simple HTML for those pages. Since then new standards have emerged, so I'm trying to write proper, modern HTML for the new version's Help Book. And this means using CSS.

For those not familiar, CSS ("cascading style sheets") is a way to separate the layout and styling of web pages from the actual text and images. You write a CSS file that defines layouts and styles, and then you write any number of Web (or Help Book) pages that link to that single CSS file. This means that all of those pages share the same layout and styles, and it also means that you can change the layout and styles for all those pages by editing the single CSS file, instead of having to edit all the separate Web pages.

That's a great thing, and it's the reason I'm using CSS for this release. It's really the right way to go. But there is a dark side to the force that is CSS: doing simple things is simple, but anything very fancy can be difficult to figure out and debug. An example: I want my Help pages to have a navigation column on the left, with constant width; and the main text on the right, taking up the rest of the page width. It takes only a few lines of CSS to do this, but it took me hours to figure out what those lines were. I made several attempts that seemed like they ought to work, but didn't. In the end, Google was my friend and found me a tutorial that showed me the right way to do it.

In addition, I'm still working on refining the styles: fonts, faces, lists, headers, menu item and button labels, and so on. Apple's Style Guide is good for this and I'm mostly following it, but there's still room to make my own decisions, good or bad. (I'm trying to make good ones.)

Now that the main layout elements are done, I can mostly concentrate on writing the text. Some of this I can copy from the old Help Book, because a lot of it hasn't changed. Other parts must be heavily edited, and some must be written from scratch. In addition I need a completely new set of screen shots, because the appearance of Solitaire Till Dawn and its dialogs and buttons and menus has changed quite a bit. I think I've got about half of it written by now, although I'll have to go over the whole thing more than once for review and editing and cleanup before it's really done.

A side benefit of writing the Help Book is that it makes me go back and test all of the features, one by one, to make sure they really behave the way I say they do. This has smoked out several bugs that I will have to fix before release.

In other news, I put some time in on Retina-compatible graphics and I'm pleased with the results. I think I won't have to hire out any artwork except for the app icon itself, which will save both money and time.

Mavericks

A few people have asked me about Mavericks, the soon-to-be-released Mac OS X 10.9. (I'm going to miss the cat names that Apple has used for all their earlier releases.)

From what I've seen so far, there's no reason why Solitaire Till Dawn won't be fully compatible with Mavericks  I intend for the new Solitaire Till Dawn to work with any version of Mac OS X from Lion (10.7) at least up through Mavericks—of course I can't promise anything beyond that at this time, since we have no idea what future OS X releases will be like.

My last post went up only about 24 hours ago, but I have been working since then. I am writing the online help. Yesterday I spent mostly fighting with CSS, trying to get the pages nicely laid out. In the process I got the first few pages of help written in the new style; their actual text content I just copied from the old version, because none of that info had changed much in the new release.

I've learned some useful trivia in the process, such as how to write "⌘" in HTML. (It's ⌘ if you're curious.)

Today I'm starting to design the pages for stuff that has changed. So I have to write new text, but at least I've mostly got the formatting problems solved now. Onward!