Sparrowhawk

Version 1.0
14 April 1996

What is Sparrowhawk?

Sparrowhawk is a GEDCOM-to-HTML conversion program for the Macintosh. It is based on version 2.5a of Gene Stark’s GED2HTML program for Windows and UN*X. Given a file in GEDCOM format, Sparrowhawk will create a set of linked HTML documents containing the genealogical information contained in the file. Within the constraints mentioned in the Known problems and limitations section (below), the output from Sparrowhawk is essentially identical to the output of GED2HTML 2.5.

Before using Sparrowhawk, I strongly suggest that you take the time to read through this document completely, and take a look at the “GED2HTML Docs” folder, which contains the documentation to the original GED2HTML program. Although some of the details may be different, the general information in those documents is very valuable.

Note: Sparrowhawk is old and obsolete. It was written before the days of Mac
OS X and Intel Macs. It still works fine on older machines running System 7,
Mac OS 8, or Mac OS 9. It also works okay in Classic on PowerPC Macs running
OS X. These days, though, there are much better ways to get your genealogy
information online. Reunion, MacFamilyTree, and most other genealogy
software now support direct HTML export. Ancestry.com will happily host
your genealogy, too. I now use The Next Generation of Genealogy
Sitebuilding (TNG) by Darrin Lythgoe for my own site. If I haven’t
scared you away, read on…

How do I get Sparrowhawk?

How do I use Sparrowhawk?

At this stage, Sparrowhawk is not very “Mac-like” and can be downright unfriendly to use at times. The program does not yield time to other running applications. For more information on these and other limitations, see the Known problems and limitations section below.

Before using the program, I recommend that you place Sparrowhawk and the GEDCOM file you wish to convert together in an otherwise empty folder. The HTML files created by the program are always placed in the same folder as the application itself, not in the same folder as the source file. Placing the application and source in the same folder, helps keep everything a bit more organized, but is not strictly required. If you want to modify the output using templates, the template files must also be in the same folder (see the Using Template Files section below).

To begin, double-click the Sparrowhawk application. A dialog will appear with information about the application. Click the “OK” button to continue.

Following the dialog is a “Get File” window in which you can choose the GEDCOM file you wish to process. This version does not allow multiple files to be processed at the same time. It also doesn’t pay particular attention to the actual format of the file, other than that it must be a text file. If you choose a non-GEDCOM file, you will get a long and very annoying string of error messages, so don’t do it.

After you’ve chosen the file you wish to process, another dialog will appear with several options you may set (note that balloon help is available for the items in this dialog).

The left side of the dialog includes checkboxes for automatic capitalization of surnames, capitalization of GEDCOM tags, generation of index files, forced generation of a GENDEX index file, and strict interpretation of the GEDCOM standard with regard to linebreaks. Note that when the “Generate index” box is checked, it overrides the “Generate GENDEX file” checkbox, so that a GENDEX file is always produced when an index is produced. This will be clearer in future versions.

“Capitalize tags” controls whether GEDCOM tag names are capitalized in the HTML output. If this option is enabled, the output files will include “BIRTH,” “DEATH,” “MARRIAGE,” etc., whereas if it is disabled, they will include “Birth,” “Death,” “Marriage,” etc.

“Strict line breaks” controls whether Sparrowhawk is strict in its interpretation of the GEDCOM standard with regards to linebreaks in CONT and CONC tags. The GEDCOM 5.3 draft standard specifies that continuation lines created using CONT are to be separated from the previous line by a newline, and that continuation lines created using CONC are not to have a newline. This setting forces a strict adherence to the standard. Most people’s output will look best with the option turned off.

The right side of the dialog contains five text fields that allow you to customize the output a bit.

“Files per subfolder” controls how many individual HTML files are placed in each subfolder. Setting this value to zero will force Sparrowhawk to create all files in a single folder (with no subfolders). Although the Macintosh file system can handle folders containing tons of files, the Finder isn’t quite so handy. I recommend sticking with the default of 100 files per subfolder. “Individuals per file” controls the number of separate individuals from the GEDCOM file that will be placed together in each HTML file. Setting the value to zero puts each individual in a separate file. Increasing this number will decrease the total number of HTML files generated. This number is ignored if the “Number of directories” is set to any number other than zero.

“Pedigree chart depth” controls the number of generations included in pedigree charts. Setting the value to zero suppresses the generation of pedigree charts. The maximum pedigree depth is 15, but any value above about 5 will result in HTML files that are difficult to read in most browsers.

“Index width” controls the maximum number of entries in each index file. Sparrowhawk normally creates a heirarchical index with at most this many entries per index file. If you set this value to zero, Sparrowhawk will produce a “flat” index, with all individuals indexed in a single file. The default, 28, works well in most situations.

“Number of directores” controls the number of separate subdirectories that will be created to hold the individual HTML files. Most of the time, you should keep this set to zero, which tells Sparrowhawk to use as many directories as necessary to fit all of the files (based on the “files per subfolder” and “individuals per file” settings). If this value is greater than zero, the “individuals per file” setting is ignored, and Sparrowhawk will put as many individuals in each file as are needed to fit everything into the correct number of directories.

This option is useful for keeping individuals in the same place after adding to the GEDCOM file. With a given set of GEDCOM data, an individual will end up in the same file every time it is processed provided that the “number of directories” and “files per subfolder” settings stay the same. That way, any external links into the genealogical data will reamain correct after running Sparrowhawk on an updated GEDCOM file. For more information, see the GED2HTML documentation.

When you’ve adjusted the settings to suit your preferences, click the “OK” button and Sparrowhawk will read in the GEDCOM file you specified and begin converting it to HTML. This process may take several minutes. During the processing, no other activity will take place, and you will not be able to switch out of Sparrowhawk. To cancel processing at any time, type command-period. The progress window will display “Done!” when processing is complete.

To convert another file, you must quit and restart the program.

So What do I do now?

Assuming all has gone well, Sparrowhawk will have created a set of files containing HTML-formated text. If you want to browse the results locally, I would suggest beginning with the PERSONS.HTML or SURNAMES.HTML files (if you chose to generate an index). The whole set of files can then be copied or transferred directly to your web server.

Using Template Files

Sparrowhawk supports the same template file mechanism as GED2HTML for customizing the HTML output. The default templates are included with the program in the “Default Templates” folder. If you want to modifiy the output, edit the template files and place them in the same folder as Sparrowhawk before launching the program.

You must not change the names of the template files, or Sparrowhawk will not be able to find them. Each template controls one type of output file: indiv.tpl controls the output for each individual; index.tpl controls the index files; sources.tpl controls the source listings; and surname.tpl controls the surname list. You can modify any number of template files. If Sparrowhawk doesn’t find a template file for a given type of output, it uses the built-in default template.

The macro language used in the templates is not for the faint of heart. The only information about the language is in Gene Stark’s GED2HTML documentation (in the section “Customizing GED2HTML with Output Templates”). I suggest you read that file and carefully compare the default templates to the output they produce before you try to create your own templates or modify the defaults.

Known problems and limitations

This release of Sparrowhawk supports most (but not all) of the functionality of the original GED2HTML program. The following features are not yet supported:

Switchable file suffixes (“.html” vs. “.htm”).
In this version all HTML files are created with the “.html” suffix. This will be a problem for people serving their pages on a DOS/Windows-based webserver.

Support for generating output selectively.
This version only supports creation of the full set of HTML files.

Processing of multiple files in one run.
Only one GEDCOM file can be processed each time the application is run.

In addition, there are several other potential problems with this version:

Hubris.
During processing, Sparrowhawk yields very little processor time to other applications. As a result, it’s not a very good idea to run the program while other time-critical applications are running. In fact, it’s probably a pretty good idea not to run anything else while it’s processing.

Xenophobia.
The computing world has a long and unfortunate history of ignoring the needs of non-English speaking people. Sadly, Sparrowhawk is no star in this area, either. Any “high-ASCII” characters in the input file are passed through to the HTML output without any conversion. As a result, most accented or otherwise modified characters (é, ü, ñ, ø, etc.) show up in most web browsers as garbage. For the time being, I recommend that you go through the source GEDCOM file and replace these characters with their HTML entity names using a text editor such as BBEdit.

Crimes Against Humanity.
Well, not humanity, just the Macintosh. In its current state, Sparrowhawk doesn’t really look or work the way a Macintosh program should, and does not take advantage of any of the Mac’s unique capabilities.

Obsolescence.
Man is this thing old. GED2HTML has continued to advance since 2.5a, as has the rest of the world. Sparrowhawk does not run natively in Mac OS X and probably never will. Because Sparrowhawk runs only in Classic mode on OS X, it will not run on recent Intel-based Macs (because these computers do not support Classic).

Not So Recent Changes

Changes Since 1.0d4

Converted to the v2.5a sources of GED2HTML. This should greatly reduce Sparrowhawk’s memory requirements.

Added to preferences dialog: control over strict line breaks, index width, and number of directories.

Fixed handling of pictures and “include” files in templates.

Lots of minor changes.

Removed expiration code.

Added Register application to distribution package.

Changes Since 1.0d3

Added support for templates.

Expiration date is now April 1, 1996.

Changes Since 1.0d2

Fixed a crashing bug when processing files with DOS-style line-breaks.

Changes Since 1.0d1

Expiration date is now february 15, 1996.

Clicking the “Cancel” button in the preferences dialog now does the right thing. In previous versions, the file would still be processed, but with the default settings. Now, all processing is cancelled.

Support for non-capitalized tag names in the HTML output. This primarily effects event names, such as “BIRTH,” “MARRIAGE,” etc. In version 1.0d1, these were always capitalized, now they can be capitalized or mixed-case, depending on a new setting in the preferences dialog.

Several improvements to the preferences dialog, including range checking of numbers and balloon help.

Random Information

Sparrowhawk requires System 7.0 or higher. I have no intention of modifying it to support System 6. It is a fat binary and will run a bit faster on a Power Macintosh (the difference isn’t as dramatic as you might expect because much of the Mac file system is emulated in the latest MacOS). Although I can’t say for sure, it probably doesn’t work well (if at all) on 68000-based Macs, such as the SE or Classic. It probably wouldn’t have enough memory to run, anyway.

Sparrowhawk was written in C using Metrowerks CodeWarrior development environment (CW8). It takes advantage of Jim Luther’s excellent MoreFiles code collection to take care of arcane file manager stuff.

Why “Sparrowhawk?” Good question. During the development of Sparrowhawk, I offered a free registration to the first person to guess why I chose that name. After lots entertainingly incorrect guesses, Kit Johnston finally guessed corectly, but turned down the offer of a free registration. The next correct guess came from JacobLeavr, who is now enjoying his free Sparrowhawk.

Okay, on with the story. When I was struggling to come up with a name, I kept returning to the “Ged” part of GEDCOM and trying to figure out why it sounded so familiar. When I asked my wife, she knew the answer, and Sparrowhawk had its name. “Ged” is the name of a wizard in Ursula LeGuinn’s Wizard of Earthsea trilogy. In Earthsea, all people and things have a common, everyday name, and a “true” name. Anyone who knows somebody’s true name has power over him or her. Well, Ged’s common name was Sparrowhawk. Voila. Are you sorry you asked?

Freeware

Sparrowhawk is now freeware. You may use use Sparrowhawk for your own personal use for free.

Sparrowhawk was previously shareware, but though still useful, it has not kept up with the latest advances in GED2HTML nor has it made the leap to Mac OS X (and probably never will). Thanks to everybody who registered the shareware version.

Disclaimer

Bradley D. Mohr disclaims all warranties relating to this software, whether express or implied, including without limitation any implied warranties of merchantability or fitness for a particular purpose. Bradley D. Mohr will not be liable for any special, incidental, consequential, indirect, or similar damages due to loss of data or any other reason, even if Bradley D. Mohr or an agent of his has been advised of the possibility of such damages. In no event shall Bradley D. Mohr be liable for any damages, regardless of the form of the claim. The person using the software bears all risk as to the quality and performance of the software. Because some states do not allow the exclusion or limitation of liability for consequential or incidental damages, the above limitations may not apply to you.