Course web pages
Every summer, we create a new set of directories and associated web pages for each course/module that we offer, under
https://www.cl.cam.ac.uk/teaching/1819/
where 1819 represents the academic year 2018/19 (replace with whatever the current or coming academic year is). The links
https://www.cl.cam.ac.uk/teaching/current-1/ https://www.cl.cam.ac.uk/teaching/current/ https://www.cl.cam.ac.uk/teaching/current+1/
redirect, temporarily, to the previous, current and following year's course directory, respectively. They can be used in other web pages to minimize the number of URLs that need to be updated every year.
This page describes the steps involved in creating these course pages.
Subversion setup
The directory
https://www.cl.cam.ac.uk/teaching/1819/
is a Subversion working directory, like many of the other parts of the main filer-hosted web site. But how our Subversion repository deals with such a course directory differs substantially from how it deals with other web pages.
The URL https://www.cl.cam.ac.uk/teaching/1819/ corresponds in our Subversion repository to the URL
svn+ssh:[Javascript required]/vh-cl/annual-teaching/1819
and not, as one might have expected, to
svn+ssh:[Javascript required]/vh-cl/trunk/html/teaching/1819
We did this for several reasons:
- The annual course directories are an ever-growing collection (we don't throw away stuff routinely), and therefore not something that everyone who checks out the main website under trunk/html/teaching/ would want to get.
- While the version-controlled content in there is small at present, it may in future also cover the actual course materials for some or all courses, which could become rather big.
Most of the files in the annual course directory 1819/ are automatically generated by the coursedb-make tool via a Makefile, and are therefore not kept in the repository. The only files usually kept in the repository are
- index-b.html – manually edited front page
- instructions-b.html – manually edited instructions for lecturers
- coursedb.txt course database – manually edited, describes which course directories and pages to create (among other things).
- Makefile – scripts for calling coursedb-make to auto-generate the remaining files
- syllabus-html/*.html – course syllabi provided as HTML files (currently only for Part III/MPhil modules)
- syllabus-latex/*.tex – course syllabi formatted using LaTeX or latex2html (currently only for Part 1A/1B/II)
To ensure that someone who checks out something under
svn+ssh:[Javascript required]/vh-cl/trunk/html
still gets to see teaching/1819/ at the expected place, we set at
teaching/ the svn:external
attribute. As a result, if you checkout the
main web site, the svn checkout command will trigger an additional
checkout of the (last two years') annual directories at the place
where they appear on the web server. However, note that what you find
in your working directory under 1819/ is actually a separate working
directory, and not just a regular subversion subdirectory.
Creating next year's pages
Step 1: create the new directory
The first step needs to be done during Lent term, when the current academic year has long stabilized and preparations for the next academic year start to begin (e.g. the Part III and MPhil admissions process):
- First, create in the Subversion repository the new annual
directory, by copying last year's directory as a starting point, with
the following command, which will directly commit to the repository:
svn cp svn+ssh:[Javascript required]/vh-cl/annual-teaching/1718 \ svn+ssh:[Javascript required]/vh-cl/annual-teaching/1819
(Adjust year numbers as required!)
- Then go in your Subversion working directory to html/ add there
the directory that you have just created above as an "external":
svn propedit svn:externals teaching
When the editor starts, add the line
^/annual-teaching/1819 1819
You may also want to retire old externals, such that only the current and the coming year are linked, but this does not have to happen immediately; it can sometimes be useful to have earlier years easily accessible. See the relevant section below.
- Now do
svn commit teaching svn update
and the new annual directory will become visible in your working directory.
- The new annual directory will not yet appear at this point under
/anfs/www/VH-cl/html/teaching/1819. You still need to run
sudo -u wwwupdate bash -c 'svn update /anfs/www/VH-cl/html/teaching'
(The post-commit script that updates the web server's public working directory uses "svn update --ignore-externals". This is to make sure that deleting an external still preserves it in the public working directory.)
Step 2: update files
The second step is that various files under teaching/1819 now need to be updated:
- coursedb.txt
- Update myear attribute for the next year, and start to update the description of the courses to reflect changes to the planned timetable. This is usually done in April/May by Lise for the Part III and MPhil modules and in July/August by Dinah for the Tripos courses.
- *-b.html
- Update the academic year mentioned (1819->1920, etc.) as well as any other changes required compared to last year.
- syllabus-html
- Lise/Joy update HTML syllabi for Part III and MPhil modules in April/May
- syllabus-latex/cst.tex
- Nicholas and Dinah update LaTeX syllabi in August, Part II units earlier (April)
- uconfig2.txt
- Add section='Course pages 2019–20 (working draft)', to warn about work-in-progress nature of the pages
Course-materials directories will be created and deleted automatically on the web site as changes to coursedb.txt are committed, for as long as ownership of the respective directory has not yet been handed over to a lecturer.
Part III/MPhil applicants can now start module selection after reading
https://www.cl.cam.ac.uk/teaching/current+1/acs.html
(If there are ucampas warning messages about missing syllabus files ../cst/Coursecode.html, then this usually means that the LaTeX syllabus for the Computer Science Tripos still needs to be updated to match coursedb.txt.)
Step 3: update the "current" redirects
Once coursedb.txt has largely stabilized, well after the end of the Tripos exams, we can update where
https://www.cl.cam.ac.uk/teaching/current/
redirects.
This involves several steps, usually performed by Markus, which can be performed after 1 July, typically in August:
- go in personal Subversion working directory to html/teaching/
- invoke "make switch-current-year"
- edit uconfig.txt to bump up the year numbers in the lines
1617(missing=1, invisible=2), 1718(missing=1), 1819(missing=1, invisible=2),
- Edit the list of links in material-b.html to add the next academic year
- svn commit -m 'changed current to 1819'
The new course materials directories are now publicly reachable; however, the CST syllabus information may not yet be up to date.
Step 4: update the CST syllabus
This section is now out of date: in summer 2020 the CST syllabus format switched from LaTeX to HTML, currently edited via CKEditor, and we no longer produce printed or PDF syllabus booklets for the Computer Science Tripos.
In August, at around the time when CST timetables are finalized, Nicholas and Dinah start to revise the LaTeX sources of the CST syllabus booklet located in
svn+ssh:[Javascript required]/vh-cl/annual-teaching/1819/syllabus-latex
Lecturers are then pointed at the drafts in
/homes/ncc25/syllabus/ /anfs/www/html/teaching/current+1/syllabus-latex/
and invited to submit updates. (For Part II units of assessment, especially those shared with the MPhil course, this may have to start as early as Easter term.)
Committing changes to the LaTeX sources will automatically update the PDF and HTML versions of the syllabus on the web site, and also rerun ucampas over course pages that include parts of the latex2html-generated syllabus text, such that the syllabus tabs of affected course directories will also be updated.
At this point, any error messages should be checked carefully, as these would indicate discrepancies between the codes of courses in the syllabus sources and coursedb.txt, which need to be resolved for all the syllabus inclusions to work.
Step 5: handover to lecturers
Sometimes after step 3, Markus asks sys-admin to update the Unix/LDAP group "teaching" to the user list
https://www.cl.cam.ac.uk/teaching/current/teaching-group.txt = /anfs/www/html/teaching/current/teaching-group.txt
which is also generated by "make".
The commands
cd /anfs/www/html/teaching/current/ make check-teaching-group
will show what changes are involved to the "teaching" group.
Markus then goes to /anfs/www/html/teaching/current/ and executes there the shellscript chown.sh in order to change ownership of all the course directories to the respective lecturers. This step requires special privileges (see end of /anfs/www/html/README.txt).
After this, an email is sent out to all lecturers:
Subject: Your filer-hosted course web pages for 2018/19 are now ready I understand you are involved in teaching a course for the Computer Science Tripos or the MPhil ACS in the coming academic year. Therefore, I have now created for you a set of web pages for your course under https://www.cl.cam.ac.uk/teaching/current/ where you can place any materials (lecture notes, example files, etc.) associated with your course. Please go quickly to the lecturer list at https://www.cl.cam.ac.uk/teaching/current/lecturers.html to find (and double-check!) your list of courses and links to the associated web pages. Then please read https://www.cl.cam.ac.uk/teaching/current/instructions.html for instructions on how to edit your course pages conveniently from your departmental Linux/macOS/Windows account. Markus (pagemaster)
Experience shows that a reminder email on this needs to be sent out before the start of each term, around the time of the deadline for printing lecture notes:
Subject: Reminder: your course web pages Gentle reminder: as you prepare your lecture notes for the coming term, please also upload them to your course web pages, which you can find at https://www.cl.cam.ac.uk/teaching/current/lecturers.html Instructions on how to do this are at https://www.cl.cam.ac.uk/teaching/current/instructions.html Thanks, Markus (pagemaster)
The preferred way for lecturers to submit lecture notes for printing is to put the PDFs onto their course materials web pages, and send teaching-admin the relevant URLs for these PDFs.
Ongoing maintenance
There will surely be various requests for updates throughout the academic year, long after the course web pages have been handed over to lecturers.
Uploading files for a lecturer
Where a lecturer simply feels unable to edit their own course web pages (e.g., because they do not have a departmental Linux account), any other member of the Unix/LDAP group "teaching" can do this for them (you can see the membership list under Linux with: getent group teaching). This includes all lecturers listed in coursedb.txt, plus anyone listed in the teaching-admin attribute there (currently lmg30, jlr59, mg797, clc32, dp341, ms725, ncc25, ckh11). These people have by default group write access to all the course web pages, and can directly drop files into
/anfs/www/html/teaching/current/Coursecode/ = \\filer\www\html\teaching\current\Coursecode\
and edit /anfs/www/html/teaching/current/Coursecode/materials-b.html and call ucampas on this file (under Linux), like any lecturer.
Updates to coursedb.txt or the syllabus
Where any of the information provided by student-admin staff needs updating, this will require edits to the relevant source files via Subversion:
- html/teaching/1819/coursedb.txt – for general information about courses (title, code, lecturer, term, etc.)
- html/teaching/1819/syllabus-html/*.html – for the Part III/MPhil syllabus
- html/teaching/1819/syllabus-latex/*.tex – for the Part IA/IB/II CST syllabus (and shared units/modules)
After a commit, the changes should automatically appear on the web site, except for pages that lecturers are supposed to edit themselves (which means that in the course directory, only the syllabus-tab page will be updated automatically).
If the lecturers or contributors of a course change after the handover to lecturers (step 5), a few things may have to be changed manually:
- The owner or group of the course directory. A course directory should be owned by the first lecturer. The folder group should be "wwwpages" for a single-lecturer course and "teaching" for a multi-lecturer course. The system will automatically update the scripts /anfs/www/html/teaching/current/{chown,chown2}.sh according to the owner and group that the directories should have. But running chown is a privileged operation for which the post-commit script lacks the required permissions, so this needs manual intervention. (It is also prudent to manually check first, if any group changes already made by the lecturer would be reset by this script before running it again.) The chown.sh script updates all directories, whereas chown2.sh updates only those where the main directory differs from the intended state.
- The membership of the Unix group "teaching". This group exists mainly for the purpose of shared folder ownership for multi-lecturer courses. It contains all lecturers and contributors of any course this year that have a departmental Unix account, plus some administrators (teaching-admin attribute in coursedb.txt). The system will automatically update the file /anfs/www/html/teaching/current/teaching-group.txt, which lists the intended membership of that group. However, updating a Unix/LDAP group is a privileged operation for which the post-commit script lacks the required permissions. The Makefile target "check-teaching-group" compares the intended and current membership of that group. Contact sys-admin to update the group accordingly.
Retire old externals
Once a year, you may want to remove older entries from the
svn:externals property of html/teaching, such that not
too many past course-materials directories remain checked out. At the
same time, it is useful to keep the full working directories in place
under /anfs/www/VH-cl/html/teaching/ for archiving.
Since the post-commit update script only uses "svn update
--ignore-externals" under /anfs/www/VH-cl/html/teaching/, removing a
line from the above svn:externals table will not actually
affect the checked-out external on the public server directory.
The next time someone manually runs "svn update" there, however, it
will delete version-controlled files there, such as
1617/index-b.html. Therefore, follow these steps to retire an external
without removing the corresponding server directory:
- Remove the oldest external by deleting the relevant line
"^/annual-teaching/1617 1617" with
svn propedit svn:externals html/teaching svn commit -m 'retired external 1617' html/teaching
- Then move the external's working directory temporarily out of the
way while you run "svn update":
sudo -u wwwupdate bash -c 'mv -i /anfs/www/VH-cl/html/teaching/1617{,.tmp}' sudo -u wwwupdate bash -c 'svn update /anfs/www/VH-cl/html/teaching/' sudo -u wwwupdate bash -c 'mv -i /anfs/www/VH-cl/html/teaching/1617{.tmp,}'