Contents

Course database

The departmental course database aims (eventually) to be an authoritative reference from which most other published information about lecture courses organized by the department can be automatically derived. Its main application is currently to generate the course web pages, but we also used it for semi-automated consistency checking with other teaching-admin publications (the Computer Science Tripos syllabus booklets, the portrait timetable).

Location

The current incarnation is the file coursedb.txt, which is recreated for each academic year and is stored using Subversion at

svn+ssh:[Javascript required]/vh-cl/annual-teaching/1819/coursedb.txt

It is also visible as an "SVN external" in a Subversion checkout of the main web site under teaching/1819/coursedb.txt, which is where it is usually edited.

Update path component 1819 (= academic year 2018/2019) as necessary.

File format of coursedb.txt

The coursedb.txt file uses the same basic syntax as the uconfig.txt files we use for configuring the Ucampas navigation tree, a nested structure of list elements and key-value pairs.

Editor support (with syntax highlighting)

Each coursedb.txt file currently describes the courses being held during one academic year.

Main attributes

At the top level, the myear attribute names the academic year using the 4-digit year in which Michaelmas term takes place, so for the academic year 2018/19, write

myear=2018,

The attributes groups, courses, and lecturers each contain entire tables of values.

Groups

Each lecture course is offered to several categories of students called classes. For example, in 2015/16 the classes we used were called part1a-cst, part1a-other, part1b, part2, part3, acs. We need to be able to group classes together that may share lectures. These groups are used in the menu structure that we generate for courses. To define a group, just add a list element in groups=(...), and to define a new class, just add a list element within that group. For example, in 2015/16 we had six classes in four groups (attributes omitted):

groups=(
  year1(part1a-cst, part1a-other),
  year2(part1b),
  year3(part2),
  year4(part3, acs)
)

In 2017/18, due to the complication introduced by Paper 3 and Paper 7, which the 50% and 75% option students take at different years, we instead used two groups "undergraduate" and "masters", and have switched off the per-group navigation bar on per-course pages for the former (as it would be too big to be useful):

groups=(
  undergraduate(
    title="Undergraduate",
    supervisions=1,
    triposexam=1,
    syllabus=latexhtmlinclude('cst'),
    navbar=0,
    teaching-admin=(dp341, ms725, clc32),
    part1a-75(title="Part IA CST 75%"),
    part1a-50(title="Part IA CST 50%"),
    part1a-other(title="Part IA NST"),
    part1b-75(title="Part IB CST 75%"),
    part1b-50(title="Part IB CST 50%"),
    part2-75(title="Part II CST 75%"),
    part2-50(title="Part II CST 50%"),
  ),
  masters(
    title="Masters",
    syllabus=htmlinclude('syllabus-html'),
    showcode=1,
    assessmentpage=1,
    teaching-admin=(lmg30, jlr59, mg797),
    part3(title="Part III"),
    acs(title="MPhil ACS"),
  ),
),

Attributes assigned to a group are automatically inherited to any class that it contains, and from there to any course that is attended by students in that class.

Each group and class needs to have the attribute

title: Defines the full name of the group or class, as it will be used on web pages, e.g. "Year 1" or "Part IA CST".

Each group (or class or type) can have further attributes, which will then be automatically inherited to any lectures that are attended by students in a respective class. The following lecture attributes are normally set via the group (or type), but may be overridden for individual lectures:

syllabus

Specify how to incorporate the syllabus for this course.

syllabus=latexhtmlinclude('cst'): create a syllabus page that contains text extracted from the latex2html-generated file ../cst/Coursecode.html
syllabus=htmlinclude('syllabus-html'): create a syllabus page that contains text extracted from ../syllabus-html/Coursecode.html
syllabus=latexhtmllink('cst'): add a link to ../cst/Coursecode.html to the course's main page
syllabus=localpdflink: add a link to syllabus.pdf to the course's main page
syllabus=clone: fetch the syllabus text from the same source as the course of which this course is a clone of (see below)
syllabus=0: there is no syllabus for this course (same as leaving it undefined)

It is also possible to specify a list of syllabus components, e.g. syllabus=(clone, htmlinclude('syllabus-html')) displays first the syllabus of the parent course, followed by the syllabus text of the clone.

materials

Specify whether and how to create a page where lecturers can add links to course-related documents and software

materials=0: do not create a page for online course materials (lecturer does not plan to provide any)
materials=1: do create a template page for materials where lecturers can add links (this is also the default)
materials=clone: create a page that automatically fetches text from the materials page of the course of which this course is a clone of (leaving lecturers the option to remove the <div class="ucampas-include-html"> element that does the copying or to add additional materials above or below it)
materials=clone-symlink: create a symbolic link (a Unix-filesystem shortcut) to materials-b.html to the corresponding file of the course that this course is a clone of (this way both materials pages have the same content, discouraging lecturers from making them different); this option is less flexible and may be more confusing to Windows users

directory

Set directory=0 to suppress the generation of any page for this course (default: 1). Setting the url attribute for any course to point to an external URL has the same effect.

supervisions

Set supervisions=1 to generate an "Information for supervisor" page for the course. Override such a group-wide setting with an attribute supervisions=0 for an individual lecture course.

assessmentpage

Set assessmentpage=1 if you want an additional "Assessment" tab to be generated for each course. We currently do this for year4 courses.

triposexam

Set triposexam=1 if the lecture has an archive of associated tripos exams that should be linked.

showcode

Set showcode=1 if you want the course materials page to display the code associated with each lecture course. We currently do this for year4 courses.

note

Optional explanatory text that will be displayed at the top of the list of courses generated for each class.

timetable-url

Optional link to timetables that will be displayed at the top of the list of courses generated for each class.

Types

Types form an alternative mechanism by which courses of a special nature can inherit pre-defined default sets of attributes, one that is independent from the classes described above. This is useful if we have different types of courses that are attended by the same class of students, for example Part II units of assessment in the Computer Science Tripos, or Part III/MPhil modules cloned from these. If we define two types for these as in

types={
  part2-unit='Part II unit of assessment'{
    heading="Units of assessment",
    classes={part2-75},
    assessmentpage=1,
    triposexam=0,
    supervisions=0,
  },
  masters-shared='Masters module borrowed from Part II'{
    heading=,
    classes={acs, part3},
    assessmentpage=1,
    triposexam=0,
    supervisions=0,
    syllabus=htmlinclude('syllabus-html'),
    materials=clone,
  },
},

then these courses just need to include one of the attributes

type=part2-unit,
type=masters-shared,

and they automatically get all the above attributes preset. These attributes can still be overridden for each course individually. The CourseDB software first looks for an attribute specified individually for a course, and only if it does not find any there, it checks the type attribute and if this does not lead to the requested attribute either, it checks for the class (which in turn may have been inherited from the type).

The following lecture attributes are normally set via the type, but may be overridden for individual courses:

heading

This attribute causes the courses on the index page with the same heading value to be grouped together (per term) under this common heading, to distinguish them from other courses. Example:

heading='Paper 10',
heading='Units of assessment',

syllabus-footnote

A message that will be appended to the end of the syllabus page. Example:

syllabus-footnote='This course is borrowed from Part II',
syllabus-footnote=*p('Borrowed from ', *a(href='../part2.html', 'Part II')),

The string associated with the type name (e.g. 'Part II unit of assessment') is a human-readable brief description of the purpose of the type, e.g. for use in interactive user interfaces. Such user interfaces must in addition also offer the default choice of no type (which is typically what most courses will have).

Courses

The courses attribute contains a set of courseid='course title'{key=value, key=value, ...} entries, one for each lecture course or module. The courseid is the course code for year4 courses, and the abbreviation of the course name used on the "portrait" timetable for year 1-3 courses. The 'course title' is the full name of the course, as it will be used on web pages, e.g. 'Unix Tools'.

The following key-value attributes can be given:

classes

The set of classes that attend this course, which is usually one of the following options:

classes={part1a-cst, part1a-other},
classes={part1a-cst},
classes={part1b},
classes={part2},
classes={acs, part3},

type

The type of course (if any) this is (e.g. type=part2-unit or type=masters-shared), leading to inheritance of default attributes as described above.

lecturer

States the crsids of the principal lecturer(s) responsible for the course. For a single principal lecturer write

lecturer=mgk25,

For several principal lecturers who share equal responsibility for the course, write

lecturer=(mgk25, fms27),

You can also still append contributing lecturers in parentheses to a single principal lecturer, as

lecturer=ijw24(bdj23)

but using the contributor attribute is now preferred.

contributor

Lists the crsids of one or more contributing lecturers. If there is more than one, put parentheses around the list, like for 'lecturer' above. Add only members of the department with departmental logins (e.g., UTOs, post-docs) who contribute significantly to organizing the course, as they will be given write access to the course materials. Do not list every external guest lecturer here.

term

State the term in which the course takes place. This can be one of the letters

P: pre-arrival course
M: Michaelmas term
L: Lent term
E: Easter term
V: long vacation

You can also append a second term in parentheses, if the course continues into another term, as in term=L(E). You can also leave the term undefined (term=) in order to indicate that this course does not take place this year, which is useful for courses that pause due to sabbatical leave.

oldnames

Deprecated: Provide a list of previous full names under which this course has been offered, to assist with creating suitable links into the tripos exam repository. Example:

oldnames=('Concurrent and Distributed Systems', 'Concurrent Systems'),

url

By providing an external URL for a course, you disable the generation of any local course directory for it. This is mainly meant for courses borrowed from other departments (e.g., Engineering, Maths), which host course materials there.

For year4 modules, we also provide the following additional attributes:

hours

How many hours does this module count for, optionally followed in parentheses by a string that details how these hours are allocated. Examples:

hours=16,
hours=16("8 × two-hour seminar sessions"),

prerequisites

Prerequisite knowledge that the student should have before taking this module, either as a human-readable text string (single paragraph, no HTML tags), or as a list of course codes. If both are present, the list of courses will be shown first (as HTML links to the corresponding course pages), followed by the text string. Examples:

prerequisites=(UnixTools, ProgC),
prerequisites="Any introductory linear algebra course.",
prerequisites="Or any undergraduate NLP course."(NLP, L90),

synopsis

A human-readable text string (single paragraph, no HTML tags) describing the course in a few sentences, preferably less than 100 words.

classmax

The maximum number of students who can take this module, e.g. classmax=16.

classmin

The minimum number of students below which this module will not take place, e.g. classmin=6.

class-limit

Deprecated synonym for classmax.

Additional course/module attributes, which are usually inherited from the classes or types, but can be overridden individually here, are described in the Groups section above.

For "Part II Units of assessment" (aka "Paper 10" courses) or other courses that are offered under separate course codes to both Part II and Masters students, we also provide the following additional attribute:

clone

This attribute causes a single course entry to create two separate course directories that share the same name and some of their attributes. The attribute value string is the course code of the second course directory, and any attributes under the course code will override for the creation of that secondary directory the corresponding attribute in the parent course entry. Example:

DSP='Digital Signal Processing'{
  type=part2-unit,
  term=L,
  lecturer=mgk25,
  clone=L314{
    type=masters-shared,
  }
}

This generates two course directories called DSP/ (parent course) and L314/ (secondary) and both courses will be called 'Digital Signal Processing'. However the type=part2-unit attribute that controls the generation of the parent course's DSP/ directory will be overridden with type=masters-shared for the generation of the secondary course L314/. See also syllabus=clone and materials=clone above for mechanisms how cloned courses can easily share text for the syllabus and materials pages with the parent course from the same source. You can even have more than two clones of a course; in this case, just write clone=(DSP{...},L314{...}). If the cloned course has a different name, add a title='...' attribute to override the course title inherited from the parent.

Lecturers

Finally, the lecturers attribute is a set of entries that specify for each crsid used the corresponding full name, in the form

lecturers={
  aac10='Prof Ann Copestake',
  acr31='Dr Andrew Rice',
  mjfg100='Dr Mark Gales'{ url='http://mi.eng.cam.ac.uk/~mjfg/' },
},

We copy these entries each year because titles (Dr, Prof) and preferred names may change over the years.

The following attributes may optionally be associated with individual lecturers:

url: For members of the department, the system is usually able to figure out automatically an appropriate home-page URL for each crsid. For external lecturers, use this attribute to specify a home-page URL manually instead.

Tools and products

The Perl 5 module /anfs/www/VH-cl/scripts/CourseDB.pm provides an object-oriented API for processing coursedb.txt files.

Applications that currently use the coursedb.txt file:

/anfs/www/VH-cl/scripts/coursedb-make: this tool generates various course-specific web pages and course lists under teaching/current/.
/anfs/www/VH-cl/scripts/coursedb2csv: this tool generates a number of comma-separated value files such as coursedb-courses.csv for applications that need this information in a relational database format. More of these can easily be generated.

History

The coursedb.txt file format and the coursedb-make and coursedb2csv tools were designed and implemented by Markus Kuhn and were first used in 2006/07. They replaced an earlier system developed in the late 1990s by Neil Dodgson.

Ideas for the future

add timetabling information, generate iCal files for students, lecturers, and rooms (this project was postponed many times due to rumors that the University will try to come up with a working online timetabling system)
automatically update an SQL server mirror of (parts of) the information of coursedb.txt (half implemented via the CSV scripts, currently no user requirement, likely only practical for a subset of the information that coursedb.txt can hold)