createcal

How Do I...

How and when do I run createcal?

To run createcal, login to a department Linux machine that has your course web files mounted, navigate to the calendar subdirectory of your course web, and issue the command

  $ createcal

That command generates the html and ical calendar files. You need to run it each time you modify some input file (e.g., after modifying the description of a lecture).

But I want to run it on my Mac. Now what?

createcal is a Perl program, and can run on anything that has Perl and the required packages installed. Probably the easiest way to get it is to simply copy the files from a standard department Linux machine. If you're running in a directory that has not been initialized by the quarterly web setup process, you have to issue a single createcal command to do the initialization. I'm not typing that command here, because it's generally a mistake to issue it, but createcal -man explains what to do.

I taught CSE XXX last year. How do I reuse the lecture syllabus from that offering as a starting point for this year's course?

Simply copy the lectures.ini file from the old course web to the new one (overwriting the skeletal lectures.ini created as part of the new course web setup procedure). If the two offerings have the same number of lectures, you're done. If the new offering has more lectures, you'll need to add [lecture] blocks to lectures.ini. If the new offering has fewer lectures, createcal will simply ignore the extra [lecture] blocks.

How do I add midterms to the schedule?

File schedule.ini will have a lecture tag on the midterm date. Replace that tag with exam. Now create an [exam] information block in file exams.ini, before the block for the final exam, and re-run createcal.

My class isn't actually meeting at the time or place the university thinks it is. What should I do?

What to do depends:

• You've changed only the location and/or meeting time, but not the meeting days
  Edit inputFiles/config.ini to update the affected Location and/or Time fields. then run createcal.

• You've changed the meeting days, and...
  • You haven't already edited any of the calendar content files
    1. Edit the (hidden) file .initconfig.ini to correct the information about your meetings.
    2. Then run createcal -init -gencals to create new basic input files and an initial calendar.html output file. View the output file in your browser to verify the calendar reflects the new meeting days.
    3. At this point you can begin editing inputFiles/lecture.ini and other content files following the usual directions.

  • You have already edited calendar content files
    Edit inputFiles/schedule.ini, changing the dates to the ones you're actually meeting on. Then run createcal.

My course has multiple lecture sections. How do I deal with that?

The files produced by the setup procedure will have registered all the lecture sections. Assuming the lectures meet on the same days and have the same content, everything should be fine as is. (If not, see the question about multiple labs on differing days.)

The calendars list events as "Lecture" but I want them to say "Meeting" instead. How do I do that?

Calendar event summary text is taken first from the Summary property of the information block (e.g., in lectures.ini), then from the Summary property of the corresponding block in file config.ini, and then set to the type of the event if neither of those exist. To change all "Lecture"s to "Meeting"s, change the appropriate Summary property in config.ini. To change it for one particular lecture, introduce a Summary property to its information block.

How do I improve the look of the html calendar?

Nearly all html elements in the calendar have a distinct class. The appearance of those elements is controlled by file calstyle.css, located in the same directory as the calendar itself. You're encouraged to change the style, and share your improvements.

Barbara's html calendars look a lot better than mine. What can I do?

Copy the calstyle.css file from one of her course webs to yours.

My html calendar has gone haywire. What should I do?

You have an html error in some content block (probably one used near where the calendar goes wrong). Find it and fix it.

My html formatting and links aren't showing up in the ical calendar. How can I get them to show up there?

You can't. The ical specification forbids html elements. createcal automatically strips them before generating the ical calendar.

My course has two sections on Thursdays, but the html calendar is showing only a single "Section" entry, with no times listed. How can I get two sections, with times?

You can't. A design goal of createcal is to avoid cluttering the html calendar. When there is more than one identical event instance on a given date, it is listed just once, without a time.

(Note that there is a distinct ical calendar for each section, allowing students to subscribe to the one they're in. Those calendars have complete time information.)

My course has two labs with identical content, but one meets on Tuesdays and one meets on Thursdays. How do I deal with that?

The initial schedule.ini will include a lab tag on each Tuesday and Thursday. Each will consume a single [lab] information block from file labs.ini, so you will need to have two successive copies of the lab information there for each distinct lab content.

Note that the event generation mechanism in createcal will generate only a single lab on each Tuesday and each Thursday, despite there being two [lab] instances in config.ini. This happens because the Days property of each config.ini block is used as a filter - an event for that block is generated only if the event date falls on a day of the week listed in the Days tag.

I want to create an event that isn't any of the standard types. How do I do that?

There is a single, catch-all event type for this use, 'other'. Add other tags to the dates of the events in schedule.ini, and [other] information blocks for the events in file others.init.

I want to create an event that will show up in the Section AA ical calendar, but not in the section AB ical calendar. How do I do that?

Add

   SectionID  AA

to the information block for the event. (To restrict events to only a certain lecture, use a LectureID tag. For labs, use LabID.)

I accidentally ran createcal with the -fetch or -init switch, and it overwrote my data files. How can I get them back?

If you didn't repeat your mistake, you'll find them in (hidden) directory .inputFilesBackup. createcal makes a single backup copy of files before overwriting.

I don't want to use these calendars. What should I do?

Simply delete the calendar subdirectory from your course web.

Event Scheduling Details

The figure above shows how event scheduling works. There are four distinct situations:

1. [every] blocks

   All information is taken from the [every] block itself. Dates are determined by applying the Days property to the course quarter.

2. Event type doesn't appear in config.ini.

   In this case all information is taken from the information block in the type-specific .ini file.

3. Event type appears in config.ini and the information block does not have a Time property.

   Each instance in config.ini generates a copy of the event instance. The event information is created by taking the union of the information block (in bar.ini in the figure) and the config.ini instance. The former has precedence over the latter. For example, if a Location tag appears in both, the one from the information block is used.

4. Event type appears in config.ini but the information block does have a Time property.

   In this case the config.ini file is by-passed, and only a single event instance is produced, using only the information in the information block.

HTML Output Details

1. HTML Pages

   createcal produces two kinds of HTML pages. The first is the calendar page, which has all course events. The second is a page that lists the dates and descriptions of only a subset of the course events. List-style pages are produced for lectures, sections, labs, and hws, so long as the course has those things.

   All HTML files are produced in the main directory, calendar. The file names are:

   • calendar.html
   • lecturelist.html
   • sectionlist.html
   • lablist.html
   • hwlist.html

2. Customizing the Output

   • Overview

     createcal's design is intended to let you customize its output in two ways:
     1. Make changes to formatting, by editing a style sheet.
     2. Make changes to the basic HTML page content, e.g., changing the title or adding a line of text before the calendar.

   • Page Formatting

     The appearance of all pages is determined by a style sheet, calstyle.css, that also resides in the main calendar directory. Most formating is based on class attributes. A look at the style sheet and the HTML page source should be enough to identify how to change an element's style. A little experimentation might help as well.

     You can change all the usual things: font size and family, background colors, borders (or not), cell sizes and spacing, etc.

   • Page content

     When you run createcal, the calendar or list it produces is combined with a template file to create the final HTML page. The template files are in subdirectory htmlTemplates. Default template files are created as part of the course web setup process, and are not subsequently modified by createcal.

     Each template file contains the HTML that surrounds the main output of createcal. That means you are free to change what surrounds the main content. For example, you can change the page title, or you can add a line of explanatory text before the main content. That is, if you want some lines of explanatory text above the calendar, add the appropriate html just above the line %%BODY%%.

     Here's an example template file for the calendar page:

     <html>
     <!-- DO NOT EDIT THIS FILE.  It was automatically created by
          a program (createcal.pl).  Edit the input files (in
          subdirectory inputFiles/) and re-run createcal instead. -->
     <head>
       <LINK REL="stylesheet" HREF="calstyle.css" TYPE="text/css">
       <title>CSE 451 Spring 2011 Course Calendar</title>
     </head>
     <body>
     <div class='title'>CSE 451 Spring 2011<br>Course Calendar</div>
     <p>
     <center><a href='subscribe.html'>Subscribe to this calendar (Google, iCal, etc.)</a></center>
     <p>
     
     %%BODY%%
     
     </body></html>
     

     The line "%%BODY%%" is replaced by the calendar when createcal is run, and the result written to calendar.html. (So, if you change the template file, you have to run createcal to make those changes visible.)

     Other Placeholders: In addition to %%BODY%%, these additional placeholders are supported:

     • %%COURSE_NUM%% Replaced by a string identifying the course, such as "CSE 403"
     • %%QTR_YEAR%% Replaced by a string indicating the quarter and year, such as "Autumn 2018"
     Note: The DO NOT EDIT warning that appears in the template file applies to the HTML output file produced from the template, not the template file itself. The HTML output file should not be edited. The template file can be edited; that's its purpose. The HTML output file is a copy of the template file, with the one change that %%BODY%% is replaced by the calendar. For the warning to appear in the HTML file, it must be included in the template as well. The warning is not intended to discourage editing of the template file, however.

ical Details

createcal generates a single HTML calendar, and so all events are placed in that calendar. For convenience, it generates multiple ical calendars - one for each lecture section, one for each section or lab, and one for office hours. (This allows students to subscribe to just the events they are interested in.) An individual event may appear in one or more of these calendars. The rules governing which calendar is chosen depend on the type of the event.

• Lecture, section, and lab events

  These are inserted into a single calendar, the one corresponding to the lecture, section, or lab. The event information must specify a LectureID, SectionID, or LabID. The setup procedure arranges this, putting that information in config.ini, so things should work as expected out of the box.

• Exam and homework events

  These are always placed in one or more lecture calendars. If no LectureID property is associated with the event, it is placed in all lecture calendars. Otherwise, it is placed in the lecture calendar(s) whose IDs are specified by the LectureID property, which may be a space separated list.

  In most cases you will want to either omit the LectureID or else specify exactly one ID.

  The only event of these types created by the setup procedure is the final exam. An exam information block is created for the final exam for each lecture section. Things should work as expected out of the box.

• Office hour events

  All office hours are put in the (single) office hour calendar.

• 'Other' events

  The event information must specify at least one LectureID, SectionID, or LabID. The values of those properties can be space separated lists. The event is put in each calendar corresponding to the specified IDs.

createcal SysAdmin Details

Overview

createcal operation is implemented as three distinct phases. The phases are connected via files, as shown in this figure:

Initialization of a course web is typically done by issuing a command that runs all three phases:

$ createcal -course cse451 -quarter 11au -fetch -init -gencals  /www/htdocs/courses/cse451/11au/calendar/

The directory argument is optional, and defaults to the current working directory if not given. A configuration file, .fetchconfig.ini, can be used in place of command line options, but is not required. The ordering of command line options is not significant. See $ createcal -man for full information on available options.

Once initialized, users can modify the .ini files and re-run the final processing phase. In the usual case, they issue this command while the current working directory is, for our example, /www/htdocs/courses/cse451/11au/calendar/. Operation defaults to the final processing stage if no processing stage argument is given:

$ createcal

-fetch Phase

Note: The fetch phase implementation is UW specific, but not CSE specific.

This phase collects the information available from online sources about the course schedule. It doesn't normally make sense to run this phase without running -init as well, or vice versa. The two are separated, though, to try to isolate the portion of the code base that is UW specific. The fact that the two phases communicate via a file allows later phases to be used when the file is generated in some other way - manually, say, or by a program built for data sources other than UW web services.

The output of this phase is a hidden file, because there is no reason for users to edit it, or even notice it is there.

Here is a sample .initconfig.ini file:

[config]
  Timezone   America/Los_Angeles
  Urlprefix  http://www.cs.washington.edu/education/courses/cse451/11sp/calendar

[course]
  Number     451
  Prefix     cse

[quarter]
  EndDate    2011-06-03
  FullQuarterName spring
  FullYear   2011
  ShortQuarter sp
  StartDate  2011-03-28
  Summary    11sp
  Year       11

[lecture]
  Days       Monday Wednesday Friday
  LectureID  A
  Location   JHN 111
  ShortDays  MWF
  Summary    Lecture
  Time       11:30 12:20

[exam]
  Date       2011-06-08
  LectureID  A
  Summary    Final exam
  Time       14:30 16:20

[section]
  Days       Thursday
  Location   EEB 054
  SectionID  AA
  ShortDays  Th
  Summary    Section
  Time       12:30 13:20

[section]
  Days       Thursday
  Location   EEB 054
  SectionID  AB
  ShortDays  Th
  Summary    Section
  Time       13:30 14:20

[holiday]
  Date       2011-05-30
  Summary    Memorial Day

The first two blocks of information come directly from the invocation - either command line arguments or the .fetchconfig.ini file. The URL is the name of the file system directory as accessed through the web server. It defaults to the UW CSE-specific form shown if no explicit information is given. (Similarly, the time zone defaults to the one shown if no explicit information is given.)

The [quarter] block contains information obtained obtained from the invocation and from web services: the dates are from web services, the remainder from invocation arguments (and parsing of those arguments into pieces useful in the next phase of processing).

The remainder of the contents are obtained from web services. There can be multiple instances of each kind of these blocks.

In addition to the block types shown, the [lab] block is also recognized. Its syntax and semantics are identical to the [section] block, except for labeling of calendar events in the final output phase.

-init Phase

This phase reads the .initconfig.ini file and produces initial versions of the files the user is intended to see and edit. Those files include both the .ini files in subdirectory inputFiles and .template files in subdirectory htmlTemplates.

-gencals Phase

This phase produces the HTML and ical output files. As a side-effect, it also updates "date hints" in the .ini files. Those hints are useful to users, and so it's recommended that this phase be run as part of initial web setup.

.fetchconfig.ini

This file is used only by -fetch stage processing, and is optional. If it exists, it must be located in the target directory. Command line options take precedence over information contained in this file.

Here's an example file, showing everything that can be specified:

TimeZone  America/Los_Angeles
URLPrefix http://www.cs.washington.edu/education/courses/cse451/11sp/calendar
Course    cse451
Quarter   11sp

Note that the time zone and url prefix properties default to the UW CSE-appropriate values shown (and so are not required inputs to -fetch processing for UW CSE).

File Backup

Whenever a stage of processing is invoked that might write some file, createcal first makes copies of existing files. Because all stages write files, a backup is always made.

The backup copy is put in directory .inputFilesBackup. Copies are made of all .ini files in inputFiles/, all .template files in htmlTemplates/, and style.css.