This is a tutorial on writing genealogical reports using the report programming tools included in LifeLines genealogy software. Nothing here (not the lessons nor the references nor the tutorial programs nor anything else) has been written with the authority or approval of the author of Lifelines genealogy software or any developer, contributor, or agency responsible for Lifelines genealogy software.
As with many web tutorials, these are written to teach the author (me) some of the fine and not so fine points of report programing for Lifelines. Although I have tried to make everything here as safe as possible for my own use because I am an idiot, I cannot and do not accept responsibility for whatever harm may occur through the use or misuse of this material. Both the instructions and the report programs included here are likely to contain errors and the possibility that they have been contaminated maliciously exists as with all material distributed via the World Wide Web.
Always backup your Lifelines databases before attempting to use any report program you may find here or elsewhere on the web.
If you do not accept the inherent risks involves in using this matterial, do not use this material at all. If you accept the risks inherent in using this material, you may not redistribute it in altered or unaltered form for profit or for payment of any media or handling fee.
In particular, because these tutorials are being built piecemeal on the fly many of them are incomplete and not thoroughly proofread. Lesson numbering and organization are subject to change without notice. Next, prev, and home links are not guaranteed to appear on every page or to be accurate when they do. Be prepared to use your browser's "Back" function.
This tutorial will not teach you how to install Lifelines, how to enter data in Lifelines, how to import or export GEDCOMs, how to create new databases in Lifelines, or how to edit and use your Lifelines configuration file. If you cannot do these things or have not done them, this tutorial almost certainly cannot help you and might make matters worse. Consult the LifeLines Documentaion (aka User Guide) which should have been installed somewhere in your system when you installed Lifelines and learn to use Lifelines as a user before attempting to write report programs.
Here is a list of links which will not be repeated with every reference to one of these documents. You should have local copies of the User Guide and the Manual which you got when you installed Lifelines. You should use them because they are most likely to match the version of Lifelines you installed. You would be well advised to download a copy of the Standard and use that local copy because it is much better to have data in one consistent format (even if that format is supposedly outdated by new versions of a standard) than to have data that straddles several versions of a standard.
This tutorial is not aimed at teaching GEDCOM structure, but it is inevitable that some aspects of this will come up. It is assumed that you have a local copy of the GEDCOM 5.5 standard (or similar version) handy. Unlike the religious institution that composed the GEDCOM standard, we do not make presumptions about what a family is or whether the relationship of parent and child imply a genetic relationship, but we do rely on records and tags having certain relationsips. Lifelines puts some restrictions on tags that are necessary for Lifelines to work, but it is now possible to enter structures which more accurately represent modern social reality in Lifelines, and it is also possible to enter pure nonsense in Lifelines. Nonsense is almost certain to happen when someone tries to enter data with only a short list of tag definitions or invents new tags without defining their use well enough. A principal problem in writing report programs is an old one in data processing that is called "garbage in; garbage out." While we will try to be flexible, if a database is screwy, it often will be impossible to make sense of it in a report.
I will assume that you have a lifelines directory somewhere and that it has subdirectories Archives, Databases, Inputs, Outputs, and Reports. This is the default arrangement and if you knew enough to change it, you should know enough to make any corrections necessary to my assumptions. I suggest that you leave the directory containing your Lifelines databases completely alone (assumed to be Databases). Do not change directory to the directory with your Lifeline databases. Do not look at stuff in the Datebases directory. Do not try to read databases in them or write to databases directly. Do what you want to do to Lifeline databases through llines or llexec. If you cannot do what you want to do with llines or llexec it is because there is a very good reason for you not to do it.
I will also assume that you have created, or will create as we go along, a test database. We are not going to cover report functions that alter the database, so the concern is not that any of the reports we attempt will corrupt your database (although you cannot be too careful). The real reason for a test database is to run test reports on very simple records and also on very complex or unusual records. Testing extremes data is part of the programming process. Records that fit the bill may not exist in a "live" database, and it would be unwise to create fictional test records in an established database. You can populate your Test database by exporting a GEDCOM from your live database and then importing that into your Test database. We will probably add some fictional records to this to illustrate some points. Some of the reports you write will be useful for use with your live database.
Since Lifelines is a command-line tool, I am going to assume you have a suitable plain-text editor and some basic command-line skills in whatever shell you use. Word processors which enter curly quotes and such even in ASCII mode will not be suitable unless you know how to get them save pure ASCII and can remember to do that when you program. If you are using Lifelines as a user (and you should be before you attempt report programming), the editor you use with Lifelines will probably be suitable for programming.
Finally, it will be very helpful, but not absolutely required, if you have some experience dabbling (or better) in some programming or scripting language such as Perl, PHP, C, or a shell, and some basic knowledge of HTML. One of the reasons this tutorial exists is that the Lifelines report language presents challenges to people who have little trouble in reaching at least the dabbling stage in other languages. You may, of course, want reports in XML or LaTeX or some other format, but this tutorial confines itself to text and HTML. This will neglect a few abilities of the report language to place things at particular spots on a printed page.
[Lesson 1]
©Copyright 2009 by Lars Eighner. Original material may be copied for personal use, but may not be sold, made available contingent on the payment of any fee or access charge and may not be bundled in any product which is sold for a fee or media charge or which requires any payment for access. In short, you cannot charge money for material I have made freely available. Software and other products mentioned may be trademarks belonging to their respective owners.