PageBuilder

What is PageBuilder?

It's a perl script that processes a directory hierarchy on the FTP side at Gamers.Org and creates html files in a corresponding hierarchy on the WWW side.

These files are created from the README and .message files, and also include a standardized menu bar and footer, as well as links to subdirectories and other key info.

What areas at Gamers.Org use PageBuilder?

Currently, only one area has been done.

PageBuilder was used to copy and transform the 3D Action Gamers' FTP Archive into the 3D Action Gamers' Archive on the WWW side.

BTW, here's a link to the 3D Action Gamers' FTP Archive using http instead of ftp. You'll see the pages come up faster, usually.

How does PageBuilder work?

There are a number of components and processes involved:

A configuration file defines the paths and key directories that comprise the FTP archive being translated and the target WWW root directory. There is also descriptive text for some directories as well as the standard headers and footers for the index.html pages.
.message files in the FTP directories are processed to get the 'description' to use for the page title, header, directory name substitutions in link lists, and changes list processing (reverse name lookup). The description is taken from the line following the first line containing "ftp://".
README files in the FTP directories contain database-like Keyphrase : Value fields that provide some of the information used to construct titles, headers, and the like.
PageBuilder traverses the FTP directories in a specific order to build its internal database while processing the README files. For example, the 3daction archive is done in this order:
- 3daction/00archives/_GAME_ (one for each game)
- 3daction/00archives
- 3daction/00bydeveloper/_COMPANY_ (one for each company)
- 3daction/00bydeveloper
- 3daction/00bypublisher/_COMPANY_ (one for each company)
- 3daction/00bypublisher
- 3daction/00byhardware/_DEVICE_ (one for each device)
- 3daction/00byhardware
  ... and so on for more categories ...
- 3daction/00utils
- 3daction/Upcoming
- 3daction/Pre-Doom
- 3daction
The index.html files are created using these elements:
- Standard HEAD from config file (one for each game)
- .www/logo.gif or .www/title.gif (if either exists)
- Standard H1 and page-specific H2 using the description from the config file, or the Game or Company names from the README.
- An htmlized README or .message file (see the HTMLizing rules, below) with references to ftp://ftp.gamers.org/pub/3daction/ removed.
- A hyperlinked list of links to games, companies, or files.
- A standard menu bar linking to the top-level directories
- The footer info from the config file, including the last-modified date of the README file (or the directory if no README).

What are the HTMLizing rules for converting text files?

Each text file contains sections separated by one or more blank lines. How each non-blank section is processed depends on the characteristics of the first line:

A Table Header begins with a Keyphrase : Value line which begins with an alphabetic
followed by one or more whitespace, alphanumeric, or & / \ $ # ~ + - . _
followed by optional whitespace
followed by a colon
followed by at least one whitespace
followed by one or more columns.
A Table Column is any text ending at an optional whitespace-colon-whitespace sequence, which is the delimiter for additional columns in a multi-column table.
Table Rows after the first one (the header/title line) have more relaxed rules - they only need to begin with a non-whitespace and can contain anything up to the colon instead of being restricted to alphanumerics, etc.
A Table Horizontal Line is also supported.
It consists of zero or more of whitespace, -, =, _
followed by optional whitespace
followed by a colon
followed by optional whitespace
followed by anything, either actual text or more columns with lines.
Any column with one or more line characters and optional whitespace will have a <HR> in the HTML. Notice that a column with only whitespace will be left blank.
A Left-justified Paragraph begins with an alphanumeric, dash, or period, with no leading whitespace.
A Centered Paragraph is the same as a Left-justified paragraph except that it has leading whitespace.
A Pre-formatted Paragraph begins with optional leading whitespace followed by any character not defined for a paragraph, above.

While processing each section:

Table sections are built using html TABLE elements with the Keyphrases in column one and the Values in subsequent columns. Lines matching the relaxed Keyphrase : Value pattern described above start new rows; other lines continue the Value portion in the second column.
Pre-formatted paragraph lines always have line breaks.
In non-preformatted paragraphs, lines beginning with whitespace, lines with no embedded spaces (i.e. only one 'word') and lines with 3 or more consecutive embedded whitespaces will always have a line break after them.
All "<", ">", and "&" characters from the source file are converted to the &lt, &gt, and &amp escapes, respectively.
Each URLish-appearing string from the source file is HREF-ized into a hyperlink by surrounding it with an Anchor containing an HREF to the URL.