Modifying a Text File (defunct)

What is a 'Text File'?

y text file, I mean a file which is not generated from the database. Just about everything under /info falls into this category (with the notable exception of this documentation), as well as a smattering of other files throughout the site. The content of these pages is stored in regular old files on the system, and appears on the web by virtue of some nice Python scripts.

Finding the Files

n general, the text files are located under the virtual host's docs directory, and have the suffix .ht. If the URL is

http://server.cs.uchicago.edu/foo/bar

then the file will be located at

/stage/w3serv/server.cs.uchicago.edu/docs/foo/bar.ht

If bar turned out to be a directory, the file could also be located at

/stage/w3serv/server.cs.uchicago.edu/docs/foo/bar/index.ht

There are a few files in unusual places that you may also want to edit:

The list of who's who in the department, which appears both on the main info page and on the people page, is in docs/info/whoswho.ht (see the convention for writing filenames).
The messages used for logging in and out, changing passwords, etc., are all stored in HT files under special/.

Editing the Files

hese text files, which are also known among the site developers as HT files, are fragments of HTML that are inserted verbatim between the standard header and footer that you see surrounding this page. As such, you can use whatever markup you like, but you should omit tags like <html>, <head>, <title>, and <body> - they'll be added by the Python infrastructure.

Of course, you should edit the files within your own development virtual host, and use CVS to commit your changes and see them reflected on the main site. You should be sure to test any changes you make before committing them.

Percent Substitution

T files automatically undergo percent-substitution (also known as URL-substitution) against a library of URLs. That means that strings like %(sect:info)s or %(person:dustin)s automatically get turned into URLs by the time the file makes it to a web browser. The important parts are the initial percent-parenthesis %( and the final parenthesis-s )s. What comes in between is a command, or key, to the URL substitution library. There are many percent-substitution keys, but the most common keys in HT files are:

wwwroot: The base URL of the current server, e.g., http://newtraell.cs.uchicago.edu.
sect:blah: The URL of [section] blah. For example, %(sect:events)s generates http://newtraell.cs.uchicago.edu/events, the URL for the Events section.
person:foo: The URL of the person page for the person with login foo. For example, %(person:dustin)s generates http://newtraell.cs.uchicago.edu/people/dustin, the URL for Dustin's person page.

The URLs generated by these keys can be extended easily like this: %(sect:info)s/services translates to the URL of the computing services page, which is the URL for the Info section followed by a slash and 'services'. Alternately, this can be written %(/info/services)s, where the initial slash starts at %(wwwroot)s automatically.

It's important to use percent-substitution, because it ensures that the URLs turn out right for the user whether she's logged in or logged out, and whether she's using the main virtual host or a development virtual host. It also allows programmers to change URLs later, and be sure that everything still points in the right direction.