## Holy Services

### Jan 'Koviš' Struhár

1.0.0.18

Abstract

Short user manual for HolyServices application

## Introduction

Primary goal of application is to bring overview into holy service planning in small parishes. Program enables registration of intentions for holy services as the members of parish demand it.

The author maintained the collecting of holy service intentions for eight years with predecessor of this program. The experience he gathered is (hopefully) imbued in this, from ground-up built remake.

As main highlights of application can be counted:

- better overview about services over the year - the main screen of application resembles to yearly calendar page with colored boxes representing holy services

- intention reuse - for the holy service client is offered a selection from intentions from previous year as they tend to be repeated or only slightly extended

- holy service clients are sometimes visually challenged - big font of screen displaying holy service detail helps them to cooperate with you

- services can be quickly filtered by priest or church to get an overview about load of particular priest/church in the parish

- output can be easily turned to web contents or spreadsheet

- no national codepage/diacritic issues - application is fully UNICODE compliant

- no database driver configuration, no administration tasks required

- easy backup - data is just one file

- open code and open, standard data format - data is just plain, text based XML format that can be converted easily to different format

- easy internationalization - with little effort the application can be extended to work in another language mutation

## Intended users

Priests, their layman helpers can take advantage of using this application.

In our parish usually one person gathers the majority intentions for the whole year in one or two sessions at the end of year. The rest of intentions is registered continuously as they come - either by responsible person or priest self.

## Hardware and software requirements

The requirements are not really dramatic - common office PC is enough. The screen resolution should be at least 1024x768 to avoid scrollbars appearance in the calendar cells.

It is rather helpful to have `.xml` file type extension having associated with your Web browser with XSLT transformation capability - any modern browser like Mozilla Firefox or MS Internet Explorer will do.

If you like to fine-tune holy service plan within of spreadsheet application (like our priest), it is practical to register `.csv` file type to be opened by your spreadsheet.

For users of Microsoft operating systems is every needed component included in the installation kit.

Linux users need the QT libraries (download on Nokia software web) to have installed on their system. The required version is min. 4.5.0. Usually this requirement is fulfilled when you have KDE desktop environment version 4.x installed.

## Quick start guide

1. After you start the application, no data file is found - wizard guiding you through creating of new data file prompts you for input of basic data - priest, church and holy service client. Feel free to precise (or extend) the input in screens opened by menu commands Definitions → Priests ... and Definitions → Churches .... Double click the field you want to alter or click on button Add <item> to define next records.

   After you close the definition screen, the filtering combo boxes on toolbar are completed by given data. If you choose particular priest/church in toolbar, they get pre-filled when you define new holy service.

2. Define holy service clients (people giving the intentions) in the same way. They are not necessary, but you might want to put them in for your information.

3. Select a year on the toolbar for which you want to create new holy service records.

4. Double click on a day cell. If the cell is not colored, there is no holy service defined for that day (and priest and church) and you are offered to create new holy service. Assign church, priest, time, optionally client and intention to the holy service.

   ### Note

   Calendar cell containing holy service without client assignment has slightly blue background. If the client was assigned, background turns in more saturated tone. See the section called “Color code”

5. Usually you need to do some report about intentions you have collected. Invoke command Print → Print (Ctrl-P) and choose a time range and format of your output. Output will be created based on current filter set on main overview - i.e. if you have displayed only holy services for particular church, in the output will be only holy services from that church, too. You will put out what you see in overview.

   Output files are located in the `TEMP` folder of the system (usually `C:\Documents and Settings\<username>\Local Settings\Temp`, `/tmp` on UNIXes. XML format is usable for printed output, for it will be displayed as regular web page in web browser. CSV format can be imported in spreadsheet applications. There you can pretty-print the data at your liking.

This is rough overview. For more detailed description read further!

## Feature by feature

Let us go a bit deeper in the feature descriptions.

### Data definitions

The priest and church records define domain for holy service filtering.

In the first round of holy service acquisition you will create quite a number of clients, but once you establish the base of your clients (which is quite stable in our parish), you begin to gain benefits. When you create holy service and assign a client, you will be offered a choice from intentions served already for this client - very often the intentions repeat. You can choose to get around by not defining client at all or define single one client for every holy service, but it is not a preferred and assumed way.

You start to edit the data by double clicking on the table cell.

All data are ordered by first column - if you change the first column in a way that causes reordering, the row with record can wildly jump to another place. This is especially annoying when you define new record. For now I consider it being a feature rather than a bug.

### Create single service

Double click a day cell if there is no holy service contained, new one gets created. If you intend to define more holy services in one day, right click on a cell and choose menu item Create new service ... and define the service. Generally you can do all modifications (add/edit/delete) by context menu on table cell, double click runs default action - create when no service is available or edit otherwise.

Note that holy service detail screen uses big font type. That makes your cooperation with visually challenged clients easier.

Client selection is easy, just start to type the surname.

#### Holy service collision

In the application are considered two holy services colliding, if they are defined to be served by the same priest in the same church in intersecting time interval. This respects setup that more priests can serve the same holy service with more intentions. Collisions are checked when you create service records.

#### Service interchange

According to my experience the clients are prone to “trade” with recorded holy service dates. Client coming later finds out that his intended date is already occupied and tries to persuade his lucky brother or sister in Christ to let him the date for whatever reason.

If they agree on switching the dates, take one of the service records, make sure that they are to be served in the same time and press Change date button so as to create collision deliberately. You will be offered to interchange the holy services then.

### Color code

Light blue cell signalizes that the day cell contains only holy service records that are not assigned to any client, yet. Saturated blue tone means that day contains at least one assigned holy service.

This color code is practical in small parishes like ours one, where is usually served max. one service a day.

However the above mentioned blue color is just a default setting - using Definition → Church Detail Settings... you can select the church and assign own color to the holy services served in the church. Still holds that assigned services are drawn in more saturated color than the not assigned ones. When church selection on the main toolbar is set to All churches and there are multiple services for one day, the cell background becomes striped to give an overview.

There is another colorful item on the main screen - month name labels. The colors here symbolize nothing more than year season the month belongs to.

### Progress bar at month name label

This progress bar shows percentage of holy services assigned to clients in given month. The rationale for this indicator is that our priest insists on having some reserve holy service in every month.

I know that we will have 3 holy services a week. I generate them with holy service generator for our church and priest, not assigning a client. Client comes and I tell him, that slightly blue cells are available - he chooses one, I assign him to a service, write down intention and “free space” indicator is updated.

Kind of overview, if you work this way - generating of unassigned services in advance and populating them on client demand.

### View filtering

The first and main purpose of filter conditions is to query the data flexibly. Another effect of filter settings is that filter being set to particular church and/or priest causes the church/and priest to be preselected when you create a new holy service.

Naturally, when you define holy service not passing a filter (filter set to church “A” and new holy service assigned to church “B”), on the main screen stays no track after the new defined record - it does not fit to current filter! Set filter on church “B” and you will see it again.

Last selected filter settings and displayed year is remembered in system registry (Windows) or configuration file (Unix) - it will be restored on next program start.

### Holy service generator

I (and my clients, too) like to see all opportunities for having the holy service - in our village we have holy service every Monday, Friday and Sunday (for instance). Behind this rough layout is are finer nuances - every first Friday in month is served holy service for children in families, every third Sunday is in our church served service for all members of parish (this intentions rotates among all three parish churches).

That is the reason for first two modes of generator - first one defines holy services in regular time spans - every Monday (every 1st Monday to express this in generator options) or every third Sunday as for the example. Basically I have two options how to setup the Sundays:

1. I generate unassigned holy service for every Sunday in year and in second run I will choose to generate every third Sunday from certain date holy service (optionally) assigned to client “all people” with intention “for all people in parish” REPLACING colliding services.

2. Or I generate every third Sunday the proper holy service with the intention and add the free holy services - now I will ask for creation of holy service for all Sundays SKIPPING the colliding services.

The other options of generator is useful for the other task - repeating of services served every first Friday, second Tuesday or whatever n-th weekday in month, basically one day in month.

Other option is to set usual service order in Definition → Church Detail Settings... and use the predefined settings in the generator. All approaches can be combined.

Press the button Generate once you are satisfied with the options.

### Warning

As with all generators, you ought to be careful - in a few seconds you could overwrite your precious hand written records.

I recommend to populate new year with generator and add the details manually after all generating is over.

### Output

All visible (passed through the current filter) holy services can be directly printed on the printer or exported to HTML (Web page), PDF (Adobe Acrobat), ODF (OpenOffice format), PostScript, CSV, iCal or XML format. It is also possible to put data in clipboard in format acceptable by Office (OpenOffice, MS Office) applications.

For all kind of output save the iCal/XML ones you can modify the order and type of columns that are exported via button Column selection... in print dialog. By dragging the columns between visible and hidden columns table you will arrange the printout. The layout is persisted in the system settings, it is not transferred with the data file - that means on other computer you get the default column arrangement..

If you would like to modify the report, I recommend you to do HTML export and modify it according to own taste. Many editor support visual modification of this web page format today. The document is immediately ready to be published on the web. Also PDF is often found on the web, but is not that easily editable.

You can also opt to do after-export modification in the CSV format (I use conditional formatting of the table to emphasize Sunday services in the list). CSV is useful to be associated with spreadsheet application, OpenOffice Calculator or MS Excel work just fine. CSV is deliberately encoded in LOCAL code page - some popular applications still tend to have problem with UTF-8 encoding. As a separator is used semicolon `;` character, since comma is very common in intention texts.

iCal format is accepted by wide selection of time organizer/calendar applications - let us name GoogleCalendar web service, IBM LotusNotes, Microsoft Outlook, KOrganizer ... They have a function to import calendar file with holy services that you just exported.

XML export contains all available information about holy services - it can be converted into web page by transformation template `defaultReport.xslt` in program folder. If you have some computer skills, you can easily edit the `xslt` file (looking into export file for tag name) to adapt the web browser page according to your desire.

It is advantageous to have assigned the XML files to web browser capable of XSLT transformation (Mozilla, Safari, Opera, MSIE) - program tries to open the exported file with associated application after the export is finished. But when you have the possibility to output directly web page format, this option is more for experts.

### Auto-save

All data are automatically saved when you close the application.

Force the saving by issuing command File → Save all

### Local holidays definition

Holidays valid for given day are visible in date cell tooltip. Additionally to general holidays that are always visible (Christmas and Eastern related holidays), you can define you own local holidays according to own taste in respective screen Definitions → Holidays... .

Holiday definition are read from `<installation folder>/holidays` folder for your language - see `cs_CZ.txt` as example - UTF-8 encoding is expected, if you decide for raw file modification.

## Files in installation folder

HolyServices.exe

  The application self, this file has to be run in order to use the application.

holidays/*.txt

  Text files keeping language (culturally) specific holidays. According to displayed language the holiday definition is loaded and displayed in the calendar cell tooltip. For example file `holidays/cs_CZ.txt` holds definitions for Czech language. You can freely add your own entries, just use UTF-8 encoding.

defaultReport.xslt

  Output data in format XML refer to this file in order to be displayed as HTML in web browsers. Edit this file with text editor if you wish to have more columns, different order of columns or whatever else different inside your browser. It is always copied to be at XML exported file.

*.qm

  User interface translations. Application is natively in English language.

*.dll

  Runtime libraries needed for application.

*.xml, *.csv, *.ics, *.html, *.pdf

  These are results of output you ever done. The output files are never deleted by application, you can delete them when you do not need them. The filename usually starts with date time section, you will see immediately, which ones are ancient ones.

untranslated.ts

  If you would like to have HolyServices application in your language, do not hesitate and translate this file! See the section called “How to add next language”.

### How to add next language

In installation folder is usually file named `untranslated.ts`. It is raw stuff for user interface translation, it contains all menus, message boxes text visible in the program.

If you want to introduce your native language to the program, open this file in UTF-8 or Unicode enabled editor (Windows Notepad, vim, PSPad) and write translation of element `source` between tags `<translation>``</translation>` respecting occasional translating hint `comment`.Make sure you store the file in Unicode or UTF-8 encoding, not in your local code page.

Of course, if you are kind of developer and you have QT library installed (can happen especially for K Desktop Environment users), use QT Linguist application to translate in dedicated environment.

Second thing to be translated is the report transforming file `defaultReport.xslt`. Translate the header texts between `TH` tags.

Send me the translation then and I will add it to public resources ASAP. You shall be rewarded greatly! I write your name into credits file, if you will not gainsay :-)

## Data files

Data files can be created by File → New ... (Ctrl-N) - the file creation wizard will guide you through the process. It is possible to have more data files, although (in my opinion) vast majority of users will come along with just one file containing their parish.

More files can mean more confusion. It is recommended to have just one main file, that will be always opened on application start. Unless you move the data file, you can forget that you have some data file - it is opened, saved automatically.

*.holyservices

  This file holds all data needed for run of program. Backup this file regularly and you are on safe side.

storedHolyServices.dat

  Data file from the versions preceding 1.0.0.11. It is just named differently, but that is only difference to regular data files.

*.archivedHolyServices

  regularly archived data files

### Auto-archivation

Data file is regularly archived to folder `archive`. Every week a compressed backup copy of the data is stored.

Hopefully you will never need to use it. But if you would, you need to use function File → Dearchive... to uncompress data and write the archived file in readable form, you will be prompted to open it immediately.

### How to migrate your data to new computer

Install the application on the new computer and copy over the data file and you can continue working with your data.

What is NOT transferred are settings like recently used files, recently selected priest/church, column selection for export. These settings reside in system registry (hidden initialization file on Linux).

### Copies of data out of sync

When working with multiple copies of data you can easily loose track on which data is the right one. If it happens that you have acquired data into two different copies of data file, having something here and something there, you can use any text editor or better text merging tool like diff or WinMerge.

## Command line switches

There are couple of command line switches you can use to parametrize the application. They can be added to the application shortcut.

--language <ISO locale abbreviation>

  forces application to run with internationalization settings of given locale (for example en_US or de_DE -Germany- or cs_CZ for Czech locale). In standard installation en, de, cs are supported.

--file <holy services file>

  opens directly given data file

--help, -?

  short overview of the parameters

## Evolution plans

I am more than happy to add new language files making software accessible new user group.

Express your wish for certain feature to me and I will consider creating it. That simple it is!