Webmaster's Guide: When You Absolutely, Positively, Have Nothing Better to Do

Stephen Peters '92,'06

original 2006


This is intended for MTG webmasters who are trying to figure out everything about how the Guild website works. It also tries to explain some of the reasoning behind the choices that were made here, as well as some of the little tricks I've used to make my life easier.

To make the most of being a webmaster, you have to know a little about a lot of things. Hopefully, this tome will go a ways towards giving you that leg up.

A formatting note: Commands that get typed in will usually appear `like so'. Other literals, like XML elements or pieces of stylesheets, will probably appear <thusly>. Filenames will simply be in typewriter font. Anything that doesn't follow these conventions is probably because I fell asleep while typing this.

1. The Quick Summary

2. The Slightly Less Quick Summary

This site is implemented using XML to store the data, and a set of translating XSL stylesheets which turn the XML into pretty HTML pages. Plus, there's a Makefile which should do all the translating for you. The important bit is that you don't want to edit the HTML directly - you edit the XML or the stylesheets.

When you're making changes, it should be as easy as altering the XML (either by hand or through an XML editor of your choice). Then, just go to the directory with this file in it, and type `make'. This will rebuild all the necessary HTML files so that people can use the website.

3. Common Editing Tasks

There's a bunch of tasks you do over and over again as webmaster. Here's an example of edits that are commonly made. After you go through these steps, you should run `make' to make everything both hunky and dory.

3.1 Ending an old show/Starting a new show

When we start a new show, the site needs to be switched over to display the new, pretty show, and not the old, dead show that no one likes anymore. Steps for this are:

Move the top <showref> line from upcomingshows.xml to the first <archive> section of archive.xml.
If the new, current, show isn't already a <showref> line, create a new [year]/[season]/show.xml file (see existing show.xml files for the format), and copy the new show information into it. Turn the show into a <showref> line in the upcomingshows.xml file.
Make sure the show.xml file has everything useful, including dates, location, a description blurb, and an <attrib> with author credits.

3.2 Opening ticket reservations for a show

The website doesn't open tix reservations until it has a <tix> section with ticket prices. When you want to open reservations, make sure that the <dates> section has an individual <date> line for each performance, and make sure that the <tix> section has a <price> for each set of people.

3.3 Closing off reservations for a performance

Sometimes we sell out, sometimes it's just nice to update the site so that the ticket reservations window isn't listing performances that you can't see without going back through time. For this, the <date> elements can have a reserved attribute. reserved="done" is for performances that have already occurred; reserved="full" is for performances that are still coming up but don't have any more tickets.

3.4 Adding pictures to a show

When your archivist lovingly sends some pictures for the website, put them up for all to see by first throwing them into a directory, generating thumbnails, and then assembling them into a photo page within the <graphics> element.

To make all this easy as pie, use the `tools/make-thumbnails' utility, which will take a directory name and a photographer name, and create all the thumbnails as well as the XML that should go in the file. Just:

> cd 2005/FAL [ or whatever the year/season is ]
> mkdir pics
 [ copy a whole bunch of image files into the pics directory ]
> /mit/mtg/www/tools/make-thumbnails pics "Joe Photo-Taker"

...and then cut and paste all the output and put it between the <graphics> and </graphics> tags in show.xml. If you want to add captions, type them in for each photo just before the </photo> tag.

3.5 After Guild Day

Ah, Guild Day. After lots of decisions get made, you should put them up. Update officers.xml with the new board members (and keep in touch so you know if there are new people for the appointed positions). Then, add the chosen future shows into the upcomingshows.xml file (it's nice to list the backup show as well, at least until the show gets a producer).

3.6 Rehearsal Schedules

For some reason, they haven't been giving us rehearsal schedules to put on the web lately. This is because stage managers are silly, and don't recognize the value of having a neat little schedule that shows everything, in a format that has been tried and tested to display info in an easy-to-read and fairly easy-to-edit format. Like I said, silly.

But if they wake up and start asking for it again, here's what to do. In the show.xml, add a line that says something like <rehearsals file="schedule.xml"/>. Then, you're going to create a schedule.xml file, which should look similar to other schedule.xml files elsewhere.

In the schedule.xml, there will be a <rehearsals> tag, filled with <day> tags that describe the rehearsals for each day. Each <day> will have an date element that defines the date.

Inside the <day> tags are <location> tags, which will list the rehearsals happening at a given location. The locations will use <place> elements to say where the rehearsal is, and a list of <rehearse> elements that say what's being done. You'll need when, who, and what elements to say what's going on.

You can also put <announce> inside the days, to put in major announcements like ``off-book,'' or who is meant by the word ``ensemble''.

And then when you type `make', it usually only updates the schedule, for a nice, quick compile.

Sadly, there's no easy way to parse the dates and automatically get rid of old rehearsals. I usually comment out old info whenever doing a rehearsal update.

4. The Grungy Information

Here's where I go into an unbelievably pedantic description of the system details. Enjoy.

4.1 The XML Bits

The data is stored into XML files accordingly:

At first glance, XML looks a lot like HTML, but it's a bit more unforgiving of errors than HTML is. Every opening tag (like '<show>') *must* have a closing tag. If you want to have an empty tag (like '<sep></sep>'), you can abbreviate it by putting the slash before the closing bracket ('<sep/>'). I won't go majorly into XML here - you can do a search for `XML' at Yahoo! or Google and get some good tutorials. If you know what a DTD is, the mtg.dtd file will describe the format pretty well - it's accurate for the most part.

The major tags we use are:

5. Version Control

I setup CVS as version control on the entire contents of the website. I did this for two reasons. The first is for backup purposes. Although I have all the faith in the world that MIT will manage to not blow away the entire MTG locker in a fit of pique, if they did do that accidentally we'd be really, really sad. So, keeping a mirror of the entire locker somewhere is a good idea.

The second reason is for change tracking. If you make a mistake and need to go back to what the website looked like a couple of days ago, you can do that (provided you're keeping up on commits to CVS).

Right now, the CVS repository is stored on an external computer owned by me, Stephen Peters, long-time Guild member. This should probably be switched to something like myfairlady.mit.edu, but I actually trust that machine far less than I trust my own, so I've set up this situation.

For security, the only way to access that external CVS repository is through SSH public-key encryption. To setup your own public key, look for information on the `ssh-keygen' program. Once you've set up the public key, it will be in your .ssh/id_dsa.pub file or something similar; email it to portnoy@alum.mit.edu and he'll make sure that you can use it to get repository access. Also, look for info on `ssh-add' to find easy ways to add the SSH key to your session so you don't have to continually type in your password. Oh, and don't forget to set the CVS_RSH environment variable to ``ssh'' or it won't work.

Updates are pretty easy. You can find lots of CVS tutorials on the web, but the commands you'll probably care most about are `cvs add', for adding a new file or directory to the repository, and `cvs commit', for committing everything you've modified.

Before you ask, yes, I thought about using Subversion. The problem with Subversion is that it uses lots of disk space to stash the unedited versions of the files that have been checked out, and with Athena quota constraints that's just not acceptable. One interesting possibility would be SVK, but that has its own problems.

6. What the Heck Were You Thinking?

A socratic dialogue on why this stuff was created this way in the first place.

So, why all this XML stuff? HTML not good enough for you?

In a word, no. The web page design involves lots of information repeatedly shown on lots of different pages, so a straightforward HTML solution would have resulted in editing dozens of pages every time the show information changed. Some of this could have been fixed with clever applications of Server-Side Includes (which, by the way, wasn't implemented on MIT's website when I started all this), but there would still have been things that would be very difficult - like making sure that the show information got properly copied over to the ticket reservations form, for example. The more places you have to type in information, the more likely it is that you'll miss something. So, whenever possible, changes are put in one place, and then copied everywhere.

Well, we could go the other way. Build our own server, and store everything in databases that are easier to edit than these XML files.

Sure. And then someone has to maintain that server. Right now MIT does it for us, and that's actually a big win.

Grrr. I really hate XML files.

Which is too bad, because I think they kind of have a crush on you.

Really? Well, that's flattering. OK, I can make my peace with them. But what about the annoying behavior of the reservations and interest forms? I mean, really, the entire ``type in a form, and it creates an email message?'' Surely there's something we can do about that!

Stop calling me Shirley. But no, this is the way that MIT allows us to have access to user-submitted data. Anything more intricate, and we're talking the build-your-own-server thing again. If MIT ever gives us access to something better than cgiemail, we should look at it. But right now, nuh-uh.

Hey, it doesn't work on this Athena workstation I'm using!

That's possible. I do most of my testing logged into the ``dialup'' servers, so I may have missed some details of the workstation environment. If you find something odd, I'll be glad to figure out how to make it work, but you might also try editing the Makefile yourself to load in whatever feature you need.

Whoa. I just looked at this LATEX handling code. What the heck is going on here?

Well, it's kind of interesting. What I do is take the LATEX file, and first turn it into a PDF using pdflatex. Then, I run it through latex2html to turn it into a .htm (HTML) file. That gets turned into XHTML (.xml extension) using tidy, which I then can plug into the website so that it looks nice and pretty.

But...but...that's insane!

Thank you.

It's not a compliment.

Neither are ugly pages that don't fit in with the look and feel of the rest of the site.

About this document ...

Converted using latex2html


Performances will be in
La Sala De Puerto Rico

September 1, 2, 7-9, & 14-16, 2017 at 8 PM, and September 3, 2017 at 2 PM

Tickets are
$6 - MIT and Wellesley students
$10 - MIT faculty, staff, and community; all other students; seniors and children
$15 - General public

Discounts available for groups of 10 or more people.

Production Staff and Cast