This project is for generating the Church Calendar for Churches of the Anglican Communion.
It can be used to:
- create a report of a calendar for a year.
- generate a calendar that can be loaded into calendar programs such as Google Calendar.
Please send feedback using the GitHub web page. It might not be looked at straight away.
In particular, please raise:
- anything that causes the program to crash.
- any incorrect input data.
- any incorrect output.
- any new or modified calendars, including data for other Provinces that are not currently recorded.
This project has been revised to change the main input format to spreadsheets as this is easier to edit.
Old format input files can be converted; see scripts/make-spreadsheets.sh for an example script.
This is an interim development (alpha) version. It should build and run, also the tests should all run now. It is an improvement on 0.2.3, in that the output is closer to correct. Also, it has been refactored extensively.
- the command line syntax has been changed.
- added a 'perpetual report' that re-presents the data from the spreadsheet.
- fixed errors.
This was an interim development (alpha) version. It should build and run, also the tests should all run now. It was an improvement on 0.2.2, in that the output is closer to correct. Also, it has been refactored extensively.
However, the calendar that I am using for testing (Hong Kong) still did not match the official calendar issued by the Church authorities, so I needed to revise the input file. Also, I needed to add some other calendars, at least the 1662 BCP calendar.
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, and print a report.
- How to build the code.
- How to modify a calendar or create a new calendar.
- How to modify the code.
USAGE:
calendar [FLAGS] --calendar <calendar-filename> <SUBCOMMAND>
FLAGS:
-f, --from_old_format read from old format input file
-h, --help Prints help information
-V, --version Prints version information
-v, --verbose Print some debugging messages
OPTIONS:
-c, --calendar <calendar-filename> Calendar file to use
SUBCOMMANDS:
help Prints this message or the help of the given subcommand(s)
i-cal Create an iCalendar that can be loaded into Google Calendar and the like
perpetual-report Create a perpetual report (for all years)
report Create a report for a given year
Each subcommand now has its own additional parameters.
Create an iCalendar that can be loaded into Google Calendar and the like
USAGE:
calendar i-cal --ical <ical-filename> --unique <unique> --year <year>
FLAGS:
-h, --help Prints help information
-V, --version Prints version information
OPTIONS:
-i, --ical <ical-filename> iCal output file
-u, --unique <unique> unique identifier for calendar **do not use domain name or email address**
-y, --year <year> Year e.g. 2024
Create a perpetual report (for all years)
USAGE:
calendar perpetual-report --report <perpetual-report-filename>
FLAGS:
-h, --help Prints help information
-V, --version Prints version information
OPTIONS:
-r, --report <perpetual-report-filename> output file for a report on the perpetual calendar (should be html)
Create a report for a given year
USAGE:
calendar report --report <report-filename> --year <year>
FLAGS:
-h, --help Prints help information
-V, --version Prints version information
OPTIONS:
-r, --report <report-filename> report output file (should be html)
-y, --year <year> Year e.g. 2024
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 program 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: aca = Anglican Church of Australia, cofe = Church of England, ecusa = Episcopal Church of the United States of America, hkskh = Anglican Church of Hong Kong.
The calendar program also can generate a report of the calendar for a given province and year.
You can use the GitHub raw links for each ICAL file to add a new calendar to Google Calendar. This will add a separate calendar which you can toggle or delete as required, without affecting your other calendars.
-
Obtain a link to the calendar of your choice by navigating to the file in the
data/calsdirectory in the GitHub web UI, then clicking "Raw". You may want to use a particular commit, in case the file paths change in the future. For example, the C of E 2021 calendar link for d4c502a is: https://raw.githubusercontent.com/martinellison/anglican_calendar/d4c502a8469f67d7e010927a9876e0b1e1781e01/data/cals/cofe-2021.ical -
In Google Calendar, navigate to Other calendars -> Add other calendars (+) -> From URL.
-
Enter the URL from step 1 and click Add calendar
Google Calendar reloads the calendar from the URL every few hours, so if you use an URL like the following, the events may change: https://raw.githubusercontent.com/martinellison/anglican_calendar/release/data/cals/cofe-2021.ical
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.
Some technical knowledge required.
-
At the moment, the programs are only distributed in source code form, so you will need to build the conversion 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/finaldirectory. If you need a different calendar, see the information below to create your own. -
Use the
calendarexecutable to create a calendar and the associated deletion file. Running this executable with--helpwill describe the options.The execution line will be something like
./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).
The calendar program also can generate a report of the calendar for a given province and year, so you can check the spreadsheet. The report is in HTML format, so load it as a file into your favourite web browser to read it. Use the calendar program with the --report my_report.html option.
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.shscript for an idea of how to do this.
Systems administration knowledge required. Rewritten for version 0.2.
Calendar data is contained in spreadsheets (with a defined format).
To create a new calendar, take a copy of one of the existing spreadsheets and modify it as required.
The spreadsheet has three worksheets:
| Worksheet | Purpose |
|---|---|
| Province | overall data for the calendar |
| Advice | description of the 'Holydays' worksheet, not read by the program |
| Holydays | list of holy days |
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 on GitHub if you can.
The main executable (calendar) generates the iCal files and a report, as selected by command line options (see calendar --help).
The functionality of the executable is performed by library crates called from the main program, so that other programs can access the same functions.
The other executables are less important.
edit_data is only used for tidying a spreadsheet. You probably will not use this.
reports was used to generate some reports about comparing more than one calendar. You will not need this.
The file todos contains some possible future extensions that are not in the initial release, but could be added later.
- 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.
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.
The calendar files that are input into the program were originally generated from calendar data extracted from Wikipedia, as listed in the list of Anglican Church calendars.
See todos for known problems and possible enhancements.