Friday, July 5, 2013

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.


  1. Keep up the great work, Rick!

  2. I so appreciate all the work you're putting into this endeavor, Rick! All good things come to those who wait! Thanks for taking the time to keep us informed of your progress.

  3. I noticed on your other blog that you have moved to Oregon!
    Just want to say welcome!

  4. No problem waiting and looking forward to plugging the end result on my personal blog. If I can figure out an appropriate hook to dissident politics, that will expand to the other blogs I contribute to. :-]

  5. So very excited as it gets closer!