facebook provides two ical feeds for third party calendar software (such as the popular Google Calendar, or (hack,spit) MS-Outlook); one for events, and one for birthdays. Unfortunately, these feeds often contain slightly broken data, or are invalidly formatted.
fbcal is a filter for these ical feeds that makes tweaks to the ical data in order to make it work better. Sometimes it's required to make it work at all...
Another useful fbcal feature is that it allows you to have multiple individually-revokable calendar feed URLs that you can give to each of your calendar-using friends. Facebook used to provide the ability to revoke the facebook feed URL (by changing the required URL 'key' value), but this functionality appears to have disappeared, possible during the recent (March 2014) facebook update.
What does it do?
These are the currently active changes:
- Move the VERSION calendar property to (near) the beginning of the file, where it belongs 
- Reduce the X-PUBLISHED-TTL value from 12 hours to (currently) 4 hours, in an attempt to persuage google calendar to update more frequently. It doesn't currently help, but one day it might...
- Fix incorrectly formatted DTSTART and DTEND event properties.
- [birthdays] Facebook's feed lists birthdays as annually recurring events (good), but lists them as only starting on their next birthday (bad, as it could be next year). I subtract 5 years so that you can see birthdays in your calendar going back at least 4 years instead of one day.
- [events] Fix incorrect escaping of commas and colons (a frequent source of calendars mysteriously not updating)
- [events] Prepend event description with the (otherwise unseen) event organiser
- [events] Suppress the PARTSTAT event property. This doesn't seem to (currently) break google calendar, but it is noncompliant, so I removed it.
These are mostly things fbcal used to need to do:
- [birthdays] Actually make start and end times begin and end at midnight, eg. due to incorrect assumptions of the local timezone or incorrect assumptions about DST.
- [events] Actually make events start and end at the right time. Events used to be specified as the correct time in the wrong (eg. US) timezone, or the correct time but not taking into account we [didn't] have daylight saving.
- [events] Some events used to have a property set (CLASS:PRIVATE) that made google not actually display any details about the event.
- [events] Suppress the ORGANIZER event property. For some reason (during Feb 2014) this broke feeds, even though importing static ical files worked fine. Go figure.
Sounds great. How do I use it?
TBD! For now, bug Michael.
This is more a note to self than anything else.
- Pepper this documentation with references (eg. to ical standards).