CGI and Perl

Planning, Design,and Layout

The structure and layout of your archive is one of the important decisions you'll make if you're just starting out. There are a number of issues to consider, and decisions to make, when you're first laying out your archive. After you've made these decisions, it won't be quite so easy to make changes to the structure and/or layout. You should plan carefully and try to consider all of the possibilities for what may happen to your archive in the future--before you ever create the first directory or file. Let's consider some of the most important issues now. Document Naming The names that you give to your documents and directories are important for several reasons. First, and possibly most useful to you as the archive maintainer, is to have some sort of notion of what's inside a document or directory, based on its name. Another consideration is whether the files and directories you'll create must be usable on DOS or other architectures that don't support long filenames.

Note:

There are essentially two schools of thought on naming file system elements. The first stipulates that one should assign names to the elements within an archive that allow for the ability to determine the contents of the file or directory based on the name. The second, also known as the ISO9660 specification, stipulates that the names should follow the 8.3 format and use only alphanumeric characters. Obviously, the restriction to only eight characters in the primary component of the name restricts your ability to assign names based on contents. You should consider whether your archive will ever need to reside on an operating sys-
tem that requires the 8.3 format (DOS), or whether you'll ever make it available via
CD-ROM. In either case, you'll probably want to choose the ISO9660 naming conventions. Don't forget the possibility that in the future, you may wish to have your archive mirrored to a system that doesn't support long names as well. If you're already running under a file system that handles long names and need to migrate or mirror your archive to a system that only handles the short names, you might have to make some major changes in order for everything to work. We'll discuss how to perform this transition later in this chapter, in the section entitled "Moving an Entire Archive," but it's definitely nontrivial.

In any case, you'll need to reserve the extension component of the filenames for MIME typing, which allows your server to properly send the browser the appropriate instructions for how to handle the document. See Chapter 5, "Putting It All Together," for more details. Be sure to check that your server's mime.types and srm.conf files follow the standard conventions for extensions, and add configuration entries to your server for any additional types that you define. Archive Hierarchical Organization The directory tree that makes up your archive is one that you'll be "climbing" up and down quite often. You should make its branches easy to remember and intuitive to understand. Each new resource in your archive will have to be stored somewhere in this tree. When you use an unambiguous, comprehensive structure for classification of resources according to their storage location, deciding where to place things (and where to find them later) will be a lot easier.

After you've decided on a naming convention, you'll want to spend some time planning the structure of the directories. Naturally, if you're using long names, you can be pretty creative with your layout; if not, then I recommend that you use some sort of simple mapping from an ordered list of eight-character names to corresponding groups or classifications.

You might point out, and you'd be correct, that the structure of the HTML document already gives the notion of hierarchy to the resources to which it refers. However, this applies only to the browser and gives no advantage to the maintainer of the documents. Creating structure, in the form of directories (or folders) in your archive, makes the HTML a bit more complicated to write but relieves the confusion and intimidation of having all the files reside in one location.

Configuration Management

This notion of structure also arises from the science of configuration management in general. We'll be discussing another aspect of configuration management, revision control, later in this chapter. Access and Security Another advantage of creating a structured archive is the ability to restrict access on a per-directory basis of most HTTP servers. Configuring the server to do this has been covered elsewhere, and I won't go into how it's done here. I point it out only to highlight the added value of planning and creating a sound directory structure for your archive. Of course, the implication is that you've planned carefully and created the structure in such a way as to use this feature selectively, another consideration in the planning stage. Top-Level Documentation Every archive directory should have some sort of an explanation of what its purpose is and, ideally, a description of the contents. Whether this description is intended only for the maintainer and/or for public access is up to you. Ideally, this file would be located within the directory that it describes. It could be the index.html and thus serve the dual purpose of describing the contents to the browser and the maintainer. This document (probably just a text file) will help the person considering a change to the archive's contents decide whether this location is appropriate for the change or addition.