Helping with Adventureland

Adventureland has been on the net since 1993, to begin with as a text file with a list of adventure games, later on as a web page. It was created by Hans Persson. The current web address for Adventureland is http://adventure.if-legends.org/. Adventureland has moved here in September 2000, however there is still a mirror of the pages online at the old url (http://www.lysator.liu.se/adventure/).

To reduce the work of adding all the information updates coming through email, I would like trying to get a few people to help with editing the information from all the emails I get to a format that my database understands. However, this means that I will need to explain what information should look like for my database to understand it. This file tries to explain that.

Adventureland is maintained in a SGML database. This file is run through nsgmls and the output is processed by a Perl script which creates all the HTML pages. Even if you don't understand what I'm talking about in the beginning of this paragraph, you can help.

In the adventureland-source.tar.gz file you will find the following files:

    gamelist.sgml - The main database file
    gamelist.dtd  - Information about the database structure
    Makefile      - "Program" that keeps track of other programs

    gamelist.pl   - Perl program that creates all HTML pages using all
                    the Perl classes
    game.pm       - Perl class for games
    machine.pm    - Perl class for computers
    series.pm     - Perl class for game series
    company.pm    - Perl class for companies
    search.cgi    - The Perl program that implements the pretty stupid
                    search engine on the main Adventureland page

If you know Perl and have a basic understanding of makefiles, you should be able to get a working copy of Adventureland set up on your own computer. If you only want to supply editing help, that is fine. That's what I need most, actually.

The only two files that you need to bother with are gamelist.sgml and gamelist.dtd. You should only edit the sgml file. The sgml file contains all the information that is used to construct all the web pages that make up the Adventureland web site. The dtd file tells my programs what the structure of the sgml file should be so the programs can automatically find formatting errors in the sgml file.

If you know HTML you will find that SGML looks similar and indeed works similarly. Actually, HTML is a dialect of SGML.

In the dtd file there are three types of lines:

• element lines ending in PCDATA
  These lines define a tag.
• other element lines
  These lines also define a tag, and then define what other tags can be used inside it. An example:

        gamelist (gtypes, machines, company+)
  

  This means that the gamelist tag should contain one gtypes tag, one machines tag and one or more company tags.

        + means one or more
        ? means zero or one
        * means any number
  

  Tags separated by "," should appear in that order in the sgml file. Tags separated by "&" may appear in any order.

All this sounds terribly technical, but if you have a look in the sgml file at a couple of examples, I think it will be pretty easy to understand. If not, please ask and I will try to clarify.

As described in the example above, the sgml file contains three sections: first a section describing all the different game types used to classify games. Read through these and make sure that you know how to classify games. The second section contains some background information about some of the computers the games in the list run on. Some of these computers have information, some not. I haven't tried to make this complete, but when someone sends me information I put it in here. Feel free to put in more information. The third section is the one that actually contains information about the adventure games. All games are listed under a company. If it isn't known what company did a game, there is a company called "Various companies" to put the game under. I try to list games under the company that programmed the game, not under the distributor (although the distributors tend to be more well-known). Don't assume that a game isn't in the list just because it isn't listed under the big-name company that sold it. There should be links (done with the <dist> and <distby> tags) between the programming company and the distributor, but these are probably missing in some cases.

An example of a company and game listing:

    <company loc=us>Personal Software
      <compdesc>
        They had plans to release Zork II as well, but never got that far.
      </compdesc>
      <see>Mainframe adventures
      <see>Infocom
    
    <game>Zork
      <type>TO
      <year>1979
      <see>Mainframe adventures
      <see>Infocom
      <for year=1980>Apple II
      <for>TRS-80 Model I
      <for>TRS-80 Model III
      <cover>zork.jpg

This is the listing for Personal Software, the company that originally released Zork. The loc=us bit means that it is a us company. Other possible values are "uk" (Great Britain), "fr" (France), "de" (Germany) and so on. The abbriviations are the same that are used for email address domains. If you don't know what country a company is from, there should be no loc attribute at all, only <company>. The text between <compdesc> and </compdesc> should be a brief history of the company in question. If you don't have a description for the company, don't put in the tag either (and this is true for all the tags below as well). It is possible to make links from this description to other pages, both Adventureland pages and pages elsewhere. Have a look at the listing for "Dr. Dumon't Wild P.A.R.T.I." for an example of how to do this. Note that the name of the company is used as the name of the HTML file, but that certain characters (most importantly, space) are replaced with underscore characters. The <see> tags refer to other companies that are related somehow. The company name must match the spelling of the definition of the other company's listing exactly (including case). These turn into "See also" hyperlinks on the finished pages.

Each game gets its own game tag. The <type> tag should refer to one of the game types listed at the beginning of the file. The <year> tag is the year of the first release of the game. Listing the year as "around 1985" is better that listing nothing at all. <see> links work the same here as for companies. For each computer that the game is available for, there should be a <for> tag. The name of the computer written after the <for> tag must be written in exactly the same way as in other places in the file, otherwise the program will think it's a new type of computer (and I prefer the <for> tags to be sorted in alphabetical order, makes it easier to see if a machine is already listed or not). If for instance the release year is different for one computer than what's listed for the game, that can be specified with attributes in the <for> tag. What other attributes are available for the <for> tag can be seen in the dtd file. The <cover> tag contains the filename for the cover scan if there is one. Putting in images requires doing other things that I don't care to try to explain, so I'll add all the images myself.

Another important tag for games is the <by> tag. There should be one of these put in for each person involved in making the game. There are some attributes for this tag as well listed in the dtd file. Look at some examples in the sgml file and it should be pretty clear what you can do, I think.

You should keep to the same formatting as I have used in the rest of the file. This means that each level of nested tags should be indented by two spaces relative to the previous one. Long texts should be wrapped and indented to the level of the first line. You should always do the indenting with spaces, never with tabs. All lines should be wrapped at 70 characters width or less.

I like Adventureland to contain as much information as possible. If there is information in the email messages that you don't know what to do with, just leave it in the mail file. There might, for instance, be information that should go on the links page. Also note that some of the mails that seem uninteresting at first ("I used to have <game> for my old TRS-80, where can I find it now?") can still contain information that isn't in the file. As you put information into the sgml file, you can remove it from the mail file. When you have put in as much as you can, send the sgml file and the remains of the mail file back to me and I'll merge your sgml file with my sgml file and try to make sense of the information that you have left in the mail file. When you remove information from the mail file, make sure that you leave the email address of the person who sent the information until you have put in all the information from him/her.

If you see that one person has sent in lots of information, suggest that he/she should be put up on the contributors' page. For that matter, feel free to make suggestions about anything about Adventureland. As of yet, most of the design decisions have been made solely by me.

Of course, anyone who sends in formatted data will be put in a special "Slaving hero" section of the contributors' page. ;-)

Stefan Meier