Synopsis

announce [ [-t] | [-n] ] [-r] [-w] {file}

Description

announce is designed to post an announcement to multiple feeds to make it convenient for students to retrieve and read announcements that are made by the course staff. Currently, it will post to a newsgroup, course website, and RSS feed.

Options

-t

Use uw.test as the newsgroup instead of the standard course newsgroup

-n

Don't post to the newsgroup

-r

Not yet implemented! Don't post to the course RSS feed

-w

Not yet implemented! Don't post to the course website

Motivation

announce is a tool designed to make posting announcements for a course more straightforward. As of April 2008, many courses use the website as the sole announcement system. This is a simple way to communicate important information to students, but it relies on students to refresh the announcements page of the website frequently, often when no new information has been posted. When this needs to be done for several courses, it can be quite frustrating.

Often a course tutor will also post announcements to the newsgroup in courses that make use of this technology. This can be quite a convenient way to get information to students because a newsreader can quickly check several sources for updates and relay to the user where updates have occurred. This is not helpful in courses without newsgroups, and some students do not prefer the newsgroup system.

Ideally, important information will be pushed to students using a variety of mechanisms. This program tries to make it convenient to post an announcement to a course website and newsgroup simultaneously. In addition, in provides RSS feed capabilities, which is a technology that has not been (widely?) adopted in CS courses until this point. The tutor merely needs to write an announcement once, run this program, and have it automatically update all three sources.

File format

The announcement files are prepared in a simple text format. The first line of the file specifies the subject of the announcement, and all subsequent lines comprise the body.

Because the newsgroup posting will be solely plain text, this file should consist only of plain text without any markup. For the newsgroup, the file contents will be posted verbatim. For the announcements page on the website and the RSS feed, the subject will be placed in a header tag (with the current date appended), and paragraph tags will surround sections of text separated by completely blank lines (in other words, "\n\n" is the paragraph delimiter). The RSS feed description (for readers that display it) will contain up to 200 characters, terminating at the final space before the 200th character that is still in the first paragraph.

Course account file structure

The newsgroup postings are not stored on the course account, so no special actions need to be taken for their inclusion. For the webpage and RSS feed, files will be placed in the directory ~/public_html/announce. If this directory exists from a previous term, it should be deleted first as announce will reconstruct it.

The text file provided to the program will be translated into a timestamped file ending in .html which contains the header and paragraph markup. As a standalone file, it is not valid HTML; it is meant to be displayed on other pages via a server-side include.

For the RSS feed, this single file is placed in a .shtml wrapper file named by the same timestamp. This is the page that will be linked to by the RSS reader. The file rss.xml in this directory will contain all of the feed information, and should be where people desiring to read an RSS feed are directed.

Lastly, this same .html file is added to a list of server includes in the file announce.shtml. This file itself should be included on an appropriate webpage where all the announcements will be displayed.