Anglican calendar
The purpose of this program is to calculate the holy days of a calendar of an Anglican church for a given year.
The program could be potentially be extended to operate for the calendar of the Book of Common Prayer, and for the calendars of other churches.
Warning: this program is currently in alpha status and may result in incorrect data. Please raise any issues on GitHub.
Also note:
- The data used to calculate holy days and dates has been derived from Wikipedia and may be incorrect.
- Each national Church of the Anglican Communion has its own calendars including local holy days, and differs from the calendars of other national Churches. Also, dioceses and local churches have discretion to vary calendars, for example upgrading, downgrading, adding or dropping holy days, moving holy days from a weekday to a Sunday and adding the dedication day of a church to the local calendar, so the calendar observed by your local church may differ from the output of these programs.
- Disputes over Church calendars seem to have historically caused more heated discussion than any other topic ever. Please do not make this a cause of dissention.
- Please raise any issues on GitHub.
- Some of the following requires technical knowledge at some level.
- There are several calendar projects on GitHub for the Tridentine calendar: here and here. This project is not related to either of these.
How to do
This section describes some of the most common things to do and some guidelines on how to do them.
- How to load the holy days of a Church calendar into your calendar program (e.g. Google Calendar) and how to cancel these holy days.
- How to generate the holy days for a new year.
- How to build the code.
- How to modify a calendar or create a new calendar.
- How to modify the code.
How to load the holy days of a Church calendar into your calendar
Create a new test calendar in your calendar system for just your Church calendar, and import the holy days into this new calendar. Then, if you want to undo the load and remove all the holy days, you can just delete the test calendar. This is just an alpha version after all.
There are generated calendars in the data/cals
directory. Most
calendar programs have some way of loading these files into your
calendar. You want to load a file with a name like cofe-2019.ical
.
Note that there may be a way to subscribe to a calendar over the internet, so if someone can set this up it may be the best solution.
Note: aca = Anglican Church of Australia, cofe = Church of England, ecusa = Episcopal Church of the United States of America, hkskh = Anglican Church of Hong Kong.
How to cancel these holy days out of your calendar
Warning: the following appears not to work with Google Calendar, and
has not been tested on anything else. You are probably better off just
deleting the entire test calendar. You did load the holy days into a
separate test calendar like it says in the previous section, didn't
you?. The data/cals
directory also contains files with names like
cofe-del-2019.ical
(with del
). These 'should' be able to delete
the entries created by the previous calendar.
How to generate the holy days for a new year
Some technical knowledge required.
-
At the moment, the programs are only distributed in source code form, so you will need to build the conversioin program from the source code (see the next section). In future, there will be pre-built executables for you to download.
-
Ensure that you have a suitable calendar data file in the format required by this program. These can be found in the
data/final
directory. If you need a different calendar, see the information below to create your own. -
Use the
anglican_calendar
executable to create a calendar and the associated deletion file. Running this executable with--help
will describe the options.The execution line will be something like
./anglican_calendar -c data/final/cofe.data -i data/cals/cofe-2019.ical -d data/cals/cofe-del-2019.ical -y 2019 -u ang-alpha
Replace cofe
and 2019
in the above as required.
The -u
parameter is to provide a unique identifier for each holy day to
the calendar system (e.g. Google Calendar) so that your calendar app
can delete the correct entries using the deletion file (see "How to
cancel..." above).
How to build the code
Systems administration knowledge required.
- The code is written in the rust programming language, so you will need to install the rust tool chain.
- Clone this repository from GitHub.
- Build the executables. See the
scripts/build.sh
script for an idea of how to do this.
How to modify a calendar or create a new calendar
Systems administration knowledge required. Also, this is a mess and unnecessarily difficult to understand.
Your options are:
- modify the file in the
data/final
directory. At the moment, the only documentation for this format is in the source code for the programs. or - use code such as in
scripts/make-data.sh
to derive a calendar data file from Wikipedia data. Good luck with this; you will need it.- first replace commas with
@
signs where they separate fields in the input data. See files such asdata/original/cofe.txt
for an example. - you can use the
edit-data
executable to modify a calendar data file. This applies some edits (in their own format). It matches edits to holy days using thetag
field i.e. the tag nmust be the same on the old holy day entry and the edit modification for the edit to work.
- first replace commas with
How to modify the code
Application development knowledge required, including the rust programming language.
The code includes documentation which can be displayed using rust
tools such as rustdoc
. Please see this documentation for additional
information about the code internals. Please raise issues and pull
requests if you can.
The functionality of the executable
The main executable generates the iCal files.
The functionality of the executable is performed by library crates called from the main program, so that other programs can access the same functions.
Possible future extensions
The following are not in the initial release, but could be added later.
- write an HTML file (file path and name) with a report for display and for web applications or write a plain text file (file path and name).
- options:
- start year from Advent (default: January 1).
- options for the cases that Common Worship allows (e.g. moving certain holy days to a Sunday, date of celebration of Matthias, etc)
- to include in the calendar:
- Sundays e.g. 16th Sunday after Trinity
- Fridays and other fasts (eves)
- ember days
- seasons and martyrs (in colour)
Points to note
- the same holy day may have slightly different names in different province and calendars. Holy Days can have 'tags' which are supposed to be consistent across calendars to enable the merger of calendars and overriding of holy day details as required.
- some minor holy days may be 'bumped' (transferred) by major holy days. See the
rules.
- note: only fixed holy days are moved, except that Patronal and Dedication replace Sunday.
- further discussion of bumping below.
- some holy days may not occur in some years e.g. whether there is, or is not, a 23rd Sunday after Trinity will depend on the date of Easter in the year and the date of Advent in the following year.
Bumping (transfer) of holy days
The program ensures that dates are bumped correctly [hopefully].
- It processes non-transferable holy days first; then checks all other holy days as to whether each should be transferred.
- Holy Days in the calendar are marked by a transfer type. The holy days with the more complex rules have their own transfer type. Note: a specific calendar may possibly not use the transfer type that is normally used for a specific holy day; and this may mean that a new calendar with an different bump rule may only be handled after the code has been enhanced to cover the new rule.
Derivation of the data
The calendar files that are input into the program are generated by
the process_data
program, which inputs calendar data extracted frm
Wikipedia, as listed in the
list
of Anglican Church calendars. The process_data
program only reads
the wiki markup for the actual list of holy days, so that needs to be
extracted and placed in a file.