Monthly Archives: October 2009

Three Steps to Apple Help, Part 1

Posted on by
2

Building an HTML Help File

The first step in implementing Apple Help is building an HTML help file.  Apple Help is the default help system in Mac OS X, and it is fundamentally a system for displaying HTML 4.01 from an application.  In order to use some (or any) of the features of Apple Help, one must do some minor customization, which is what I intend to describe here.  (The actual writing process is left as an exercise for the reader.)

For an overview of Apple Help, see this Apple Help Programming Guide.

Any decent HTML (or text) editor can be used to produce the necessary help files, but since ours is a help system for a product available on both Mac OS X and Windows, it makes sense to start with a full-featured help editor under Windows.  In our case, we use Help & Manual, which is an excellent and capable product.  (Note that we still choose to use the older H&M 4, since version 5 added the silly ribbon toolbar interface.)

Starting with a help project appropriate for Windows HTML Help (.chm), and with a tool that either works with or exports separate HTML files, there are only a few extra steps required to make an equivalent version for Apple Help.  In H&M, you use the ‘Browser-based Help’ option to write the necessary HTML files (as described later).

The common method of accessing a topic in HTML Help (as well as in the older WinHelp format) is via help context numbers.  Apple Help, on the other hand, uses a named anchor tag for each topic that needs to be accessed directly from an application.  For example, for a topic referenced as ‘contents’, you would add the following HTML tag to the topic:

<a name="contents" />

A similar tag should be added to every desired topic page, each with a unique name.  In H&M, this can be done by using the ‘Insert|Plain HTML Code…’ menu option, or you could edit the HTML directly, of course.  I found it most useful to have the basic tag on the clipboard, paste it onto each page, and then directly edit/add the name portion.

Important Note: Do not use spaces or capital letters for the topic names. Apple Help seems to have trouble finding such tags, so context help and searching may fail.

The next step is to export the separate HTML files (if necessary).  In H&M, this is accomplished by generating ‘Browser-based Help’ (via ‘File|Compile Help File…’ or the toolbar).  First, however, you will want to click ‘Customize Browser-based Help’ and make a few changes to the default options.  On the ‘Layout’ page, select the page layout that puts everything in the same window (i.e., no frames, no scripts).  Next, on the ‘Popup Topics’ page, select ‘HTML encoded topics’, which should remove any Javascript.  Finally, on the ‘HTML Export Options’ page, change the ‘Extension for HTML topic files” to “.html” (from “.htm”).

Once your help files are together, you need to add two custom meta tags to the header of the main help page (the one you want to display when the help is opened generically).  The “AppleTitle” meta tag sets the title of the help file, and the “AppleIcon” meta tag sets the name of the help icon (described below).  For Pretty Good Solitaire Mac Edition, which has all the help files in a ‘Help’ folder, we add the following lines inside the page header (<HEAD>) of our contents page, just after the title (<TITLE></TITLE>):

<meta name="AppleTitle" content="Pretty Good Solitaire Help" />
<meta name="AppleIcon" content="Help/help.png" />

The help icon (‘help.png’, in the above example) should be a 16×16, 32-bit image (with alpha transparency) that represents the help file, usually a small version of the application icon.  Place this image in the same folder with all of the HTML files.  Note that Apple Help in recent versions of OS X do not display the help icon prominently (if at all), but help icons were important in earlier versions.

Finally, in order to appear similar to other Mac applications, you will want to change the fonts in your CSS (you did use CSS, right?) to prefer ‘Geneva’ over ‘Arial’ for the display font.  H&M generates a ‘default.css’ file, so to make this change, you need only replace each instance of “font-family: ‘Arial’;” in this file with “font-family: ‘Geneva’, ‘Arial’;” and you are done.

As a final hint, if you are using Help & Manual, you can provide a link to the keyword index (automatically generated) by manually adding a link similar to the following (for the ‘pgsme’ project):

<a href="pgsme_kwindex.html">Help Index</a>

At this point, you should have a folder containing all of the HTML files for your help system, with the necessary tags, and a help icon file.  Now, just prepare to transfer these files onto your Mac development system and wait for the second installment, in which I will explain how to generate the Apple Help index and add the help files to an Xcode project.

Vote for Us

Posted on by
Reply

One of our titles is nominated for an Epsilon Award.

Epsilon Award

This year, Most Popular Solitaire 2.0, has been nominated for an Epsilon Award, the software award associated with the European Software Conference, which takes place November 7-8, 2009, in Berlin (Germany, in case anybody is confused about that).

Unlike other software awards, there are no categories here; only one award is presented each year.  This year (again) there are 25 nominees, and our product is the only game title nominated.  Accordingly, we would appreciate your vote.

Today is the last day of voting, so please vote (for us).

On the voting page, you will find the following description:

Most Popular Solitaire 2.0 by Goodsol Development, Inc. Most Popular Solitaire is a collection of only the 30 best and most popular solitaire games (selected from a collection of hundred of different varieties). There are versions for both Windows and Mac OS X, with combined high score charts and interchangeable save games. Its great popularity in Windows is even surpassed on the Mac, where it has been in the Top 20 at the Apple Store since its release. http://www.moposol.com/ Gregg Seelhoff

Voting is basically open to anybody and everybody (i.e., the “public”), so if you are reading this, you probably qualify.  To vote, simply go to this page, click on the (above) graphic with “[VOTE]” superimposed, and follow the instructions.

(Note that I would have included a ‘Nominated for the Epsilon Award’ image here, too, except that they are only available for 2006-2008, and those are really, really ugly.)

Thanks!

Windows 7 Escapes

Posted on by
Reply

Microsoft releases its latest operating system.

Last week, Microsoft published Windows 7, the successor to Vista, to some fanfare.  The reviews have been fairly positive, perhaps because Vista softened the audience, but it seems that the sales tag line should be “Windows 7: what Vista should have been.”

We tested the new operating system, in a couple of virtual machines, by running Sun VirtualBox virtualization software.  My first impression was that this was a great product — VirtualBox, I mean.  Although I have not yet delved into the advanced features, it did exactly what we needed with a minimum of fuss and bother.  We were able to test both Windows 7 x86 (32-bit) and Windows 7 x64 (64-bit) on the same 32-bit Vista host system without serious problems.  In fact, the only problem we experienced was an inability to find a 64-bit sound driver through Windows Update (so our x64 VM did not have sound).

Back to the operating system, we found it to be perfectly adequate.  It performed as expected and was easy to use (for somebody already used to Vista, anyway).  There is nothing particularly revolutionary, but (as with the update from Windows 98 to Windows 98se) everything seems to be more polished, with a few minor features added.  The big change, really, is that the 64-bit version is becoming mainstream (whereas the 64-bit support for the previous versions was not quite ready for prime time).  It is for this reason that I am likely to upgrade my development system to Windows 7 x64 in the near future.

Some of the changes include the ability to “pin” an icon to the task bar (replacing the Quick Launch toolbar), and a new management feature for task bar (a.k.a., tray) icons, allowing the user to control when these icons are displayed or hidden.  In order to encourage users to make use of this feature, Microsoft kindly made their own icons here very ugly, so the first customization item is to get rid of them.  (This will also facilitate ignoring the loads of useless preinstalled junk that comes on some new computers.)

As far as developers are concerned, nothing much has changed.  As long as your software is Vista-compliant, it will probably run unmodified under Windows 7. All of our recent product releases worked just fine; the only items noted were the (now) missing Quick Launch toolbar and the task bar icon disappearing (i.e., being hidden) after its first appearance.  The only significant caveat, though, is that 16-bit applications (those built for Windows 3.1) will not run (directly) in Windows 7 x64.

Of course, I do have a couple of recommendations for Microsoft to consider in the future.  First, they should probably do a better job of considering the symbolism they (perhaps, inadvertently) put forward.  The default wallpaper for the beta and release candidate versions of Windows 7 was a male Siamese Fighting Fish, also known as a betta.  (“Get it?”)  The latter name may be punny, but the fact that these fish (at least at the pet store) have to have separate enclosures because they are nasty and do not play nicely with the other fish suggests that Win7 is intended to be likewise.

Also, perhaps underlining the above weakness in Microsoft’s overhyped marketing capabilities, I will point out that they had great successes with Windows 3.0 and Windows 3.1 (standard version numbering), as well as Windows 95, Windows 98, and Windows 2000 (release year numbering), moderate successes with Windows 286/386 (hardware support), Windows NT, and Windows XP (opaque version lettering), but commercial failures with Windows Me, Windows Vista, and even Windows (1.0, initial release) itself.  I suggest that Microsoft stop trying to “evoke” some greater vision and stick to practical version identification.

Finally, I note that the “Starting Windows” screen of Windows 7 is the best feature of the product, nearly perfect for its purpose.  It is too bad that the same design was not carried through to the system icons, which really are a step backwards in aesthetic terms.

How I Spent My Summer Vacation

Posted on by
5

Here is what I did while I was not posting during August and September:

I broke my leg.

During a soccer game, I made an aggressive move toward a 50/50 ball at the edge of the box, looking to score.  Unfortunately, it turned out to be more like 49/51, and I lost, getting kicked solidly in the right shinguard as the ball was cleared.  I pulled myself out of the game and tried to walk it off, and though the pain did not subside, I went back in and finished the game despite my “nasty bruise”.  However, after a week of hobbling around with little improvement (and funny discoloration), I went to get an x-ray and found that my leg was actually broken.

We lost the game by a couple of goals but still finished the season in 3rd place (out of 7 teams) with a 7-5 record and a +27 goal differential.  Thanks for asking.

The actual injury was an anterior malleolus fracture to my right leg, which is a break to the tibia (the larger, weight-bearing bone).  While it is technically a broken leg, the doctor said to think of it as a badly sprained ankle.  Essentially, the ligaments in the inner ankle are so strong that instead of tearing, they actually pull a piece of the bone off.  The cool bit is that x-rays are now digital, so I have a CD-R with images of the original break (but I’m not sharing).

I was initially on crutches, and then used a “rollabout” (which was an out-of-pocket expense because our insurance would not cover an “upgrade” from crutches, despite the prescription) for three weeks.  It is amazing how quickly one loses muscle mass in an unused leg; my calf became the smallest it has been since I was in middle school.  I spent three more weeks in a boot/cast, and at the end of that time was told that my break had healed “perfectly”, though I am still facing many more weeks of exercise to get “back to normal” (whatever that is).

Our web server was end-of-lifed.

We found out, in the most inconvenient way, that our Ubuntu (Linux) web server had been “end-of-lifed”, and was no longer viable.  All support for that version was pulled, so a standard package reinstallation failed, leaving the whole system non-functional.  I had to spend a couple of days rebuilding and reconfiguring the system with a newer version, and it was painful.

This episode is exactly why Linux will never be able to challenge Windows or Mac OS X for the general desktop market.  Despite all of the amenities that make it more consumer-oriented, Ubuntu still requires an operator to be a fanboy to avoid such issues.  Nothing ever told me that the OS would be orphaned/abandoned in 2009, and it took more than an hour doing web searches to even figure out what had happened, nevermind finding the solution.  (In contrast, the NT server box OS has only been upgraded once in 13 years, from NT4 to Win2K, when the hardware failed.)

More succinctly, Linux could not survive without Google.

We reassessed our entire marketing plan.

Our marketing plan is defined very broadly, and it incorporates not only the standard concepts associated with the word, but also general business strategy.  We reconsidered the balance of the various aspects of our development, the status and priority of current projects, and future opportunities.  We evaluated and devised/updated plans for new technologies, platforms, and markets.  This updated blog is just one tangible aspect of our far-reaching plans for success.

Two words: World Domination.

I worked (hard).

In the midst of everything else, I was doing loads of development work.  I made a good breakthrough and huge progress on a major project.  We are now in that “10% of the development takes 90% of the time” phase, though, so things are seeming to be (though not actually) slowing down a bit.

Now that Fall has well and truly arrived here in Michigan (although not before just one more trip to the beach, broken leg and all), and in spite of all that life is throwing at us now, it is the right time to really get things done.  We have our plans, our goals, and our ambitions clear, so all that is left is to execute.

That should be the easy part… 😉

Where to Start

Posted on by
Reply

A few highlights of the original Gamecraft incarnation.

After importing all of the (250) posts from the original incarnation of this Gamecraft blog, during the editing process that was necessitated by the technology change, I had the opportunity to review many of the older posts.  I found lots of fascinating information (compared to just a few irrelevant bits), so I decided to provide a few pointers for those (i.e., most readers) who have not read the entire blog.

The most recent posting to receive attention was Making Mac Disk Images Pretty, which describes how we improved the appearance of Pretty Good Solitaire Mac Edition 2.0 [linked from C-Command Software/DropDMG].

The best series began with Quality: An Introduction (running through Quality: The Index), discussing our guiding principle of Quality as applied to (game) software development, posted in May and June 2006.

The most controversial post was my critical review of Microsoft Visual Studio 2005, which incited a debate and continued to collect comments well after VS2008 was released.

The best quote was from Voltaire: “Le mieux est l’ennemi du bien“; this translates to ‘The best is the enemy of the good.‘ [from MVP Backgammon Professional]

The worst month for posting was definitely August, during which month I only posted once over 5 years [in August 2008], a full score less than the expected (average) number of posts in that time.

This is just a small sampling from the first phase of this blog, but there is plenty more, all still available (twice over).  Now, we move forward and begin the second phase in earnest…

Gamecraft 2.0

Posted on by
3

This Gamecraft blog gets a face lift.

After nearly 5 years and exactly 250 posts, it was about time to update the appearance and features of this blog site, so here is the new Gamecraft 2.0.

Obviously, the aesthetics have changed substantially (and are likely to do so again in the future).  Technologically, I have switched to WordPress, from Blogger, and the entire publishing path is now internal (rather than editing remotely and hosting locally).  This change also means that the blog is generated dynamically from posts stored in a database, rather than a large collection of static(-ish) pages.

One of the nicest new features is the addition of a search function for the blog.  I was able (after some manual editing) to import all of the previous posts into this new blog (the ‘Older posts’ category), though I chose to lose (rather than relink) all of the comments in the process.  I did, however, retain the original Gamecraft site at https://blogger.gamecraft.org for archival purposes.

I know that there will be some teething pains as I relaunch this blog, so please let me know if/when you find issues.

Thanks! 🙂