Case Study: Redeveloping a web site with PPWizard

I am a member of a South African based Science Fiction club. And the webmaster of the club's web site. In December 2003 I had some time at hand, and redeveloped the web site with PPWizard.

This case study covers my experiences. It is hoped that it would be of help to people having a web site that have become just too much to maintain by hand.

Why redevelop?

After a couple of years, there were parts of the web site that were seriously out of date, and parts that were obsolete. Other parts were in serious need of some attention and care.

I have maintained the web site using Mozilla in edit mode. This was unsatisfatory for two reasons: For one, I was unhappy with the ammount to HTML code generated, where I had no idea what the code meant and did.

For another, there were a bug with the generated code, in that the background image would always be reset to the path on the development machine, and not the relative address to the image resource. This meant that I have to go in and edit the page by hand after every change done with Mozilla.

The original site design was also frames based, with the home page a T shaped 3 frame design, with a graphical logo on top, a table of contents on the left, and the requisite information page on the right. I was unhappy with this design, and was looking for a non-frames based design.

What I wanted to achieve

1. To understand the site. I wanted to understand where every page resource was, and wanted to group things together logically. For instance, I wanted all images to be in an Image sub directory.
2. To have a site that is simple to maintain. It is no use to have a glorious web site, if it is too much trouble to maintain. This is the major reason why I was thinking about moving to PPWizard.
3. To have a standards compliant site, that every browser should be able to display without any trouble.
4. To have small and efficient pages, with the minimum of images, since a lot of my target market are accessing the Internet via dial up.
5. To add new features, where applicable.

What I achieved

1. I reduced the number of sub directories from seven to five, including room for expansion, with almost all (15) pages in the root directory of the web site. Each sub directory have a specific purpose. I reduced the number of main pages from ten to eight, and cleaned up the information that were obsolete.
2. In some ways the new development site have more files than before, but less of them needs to be changed to regenerate the web site.
3. The two standards I settled on were HTML 4.01 and CSS2. HTML 4.01 is a mature standard, with decent documentation and decent validation tools. Even so I could not fully comply with the Strict version of the standard, and had to settle for the Transitional standard. This is partly due to some design desicions I made, and partly due to the PPWizard #import directive, where I was unable to figure out how to fully ensure Strict HTML syntax in the generated tables.
   Cascading Style Sheets level 2 is a different beast altogether, with horrible documentation. Even when I rolled out the new web site, I was still unhappy about certain things I have not been able to figure out on the CSS2 documentation. A special problem was that the validator is only able to check for valid CSS2, not correct CSS2. And it was with the correctness of my style sheet that I had the problem.
   I also made the concious decision to make use of relative addressing and measurements, and not absolute. So that the same page are displayed in a similar manner at different resolutions.
4. The new pages looked a lot cleaner than the previous pages, and I was serious about not using a lot of images.
5. The major new feature I added was a favicon: An icon associated with each of the pages of the web site.

While developing, I also made the decision to standardize all images to the PNG format, where possible. My (new) favourites icon and the page background are the only two image resources that are not in PNG format. This is a style issue more than anything else.

Documentation

I really hated the documentation for CSS2. I always had the problem of finding the scope of where directives was valid, and where not. The main problem I had with the documentation was that all the basic directives are documented, in a basic fashion. But anything more advanced, such as how to mix and match directives to get the result you wanted, at more than basic level, was conspicious by it's absence. In the end I managed to get something working, but I was unhappy with it, and are still trying to find out how to get a table centred on a page.

The PPWizard documentation fall between these two experiences. Once again, the basic elements are covered in detail. Some of the intermediate functionality are also covered. However, I found the advanced stuff to be covered in insufficient detail. Or, in other words, I could often not figure out if what I wanted to to was possible, or how to do it, using the documentation.

I do not know how much of this is due to the fact that I am not a full time programmer, and need a little bit more sympatetic documentation. I do feel that more of the examples should include not only the code on what to do, but the resulting generated HTML. I do not know how much trouble that would be for the author to generate.

I also found the INF format documentation for PPWizard to be much easier to use than the HTML format documentation.

I have also not contacted the author of PPWizard for assistance, first trying to see if I could redevelop the site with only the supplied documentation and published articles.

PPWizard

So, what is PPWizard? PPWizard is a HTML pre-processor. A program to generate HTML pages from a PPWizard template file or files.

It is also a REXX pre-processor, and is written in REXX. If you can program in REXX, PPWizard is understandable.

Why PPWizard? Because ever since I read some articles on OS/2 e-Zine on PPWizard, I thought that it might be useful, and help me with looking after my web site. It just took longer than I anticipated to get round to it.

I installed the newest version of PPWizard available at the time, namely 03.268. (Versions 04.026 and 04.051 have since been released.)

PPWizard Source files

The two standard PPWizard file type are the template file, extention .it, and the header file, extention .ih.

The template files can be regarded as source files of HTML pages.

The header files are the files in which PPWizard definitions are declared for use in the template files.

I created a template file for each HTML page, a shared header file, with common definitions used in all HTML pages, and a couple of page specific header files.

I also created a project file, with the .ppw extention, where I declared the list of input files, the output directory, and the depends directory.

I have a bit of a problem with the project file. I originally planned to have a web site structure with a set of pages in a sub directory. (Directions to various venues) However, I could not find anything in the documentation on project files that told me how to set this up the way I wanted to do it. I had to settle doing it the way the PPWizard documentation showed it done.

I also could not find out how to declare each template file individually, in the project file, but had to declare all of them with a *.it directive.

The output directory works well, as does the depends directory. In the depends directory PPWizard generates the dependancy files, showing how each HTML page fits together. When generating a new set of HTML pages, PPWizard checks the dependancy chain to see if any file in the chain have changed, and then generates new HTML pages only for the pages where a file have been changed.

This sounds like a slow process. It is not. My 15 pages are usually generated in about 5 seconds. This include all dependency checking.

PPWizard basics

At the heart of PPwizard are 3 directives, namely #define, #evaluate, and #include. Once you understand how and where to use these three directives, you are well on your way to be able to generate new HTML pages.

#define

With the #define directive, you declare a definition and assign it a value. This definition is then available for use elsewere.

Example: #define MyName A.L. du Pisani

This assigns the value "A.L. du Pisani" to the definition MyName. As you can see, the value can consist of more than one word, and may even span multiple lines.

#evaluate

With the #evaluate directive, you calculate a value and assign it to the definition. This calculation can happen immediately, or can be defered until needed. The calculation consistes of a REXX command or set of commands, or a PPWizard macro. (Which is written in REXX)

Example: #evaluate LastUpdateDate FormatTime("%d %B %Y")

This calculates the date in the format "Day Monthname Year" and assign it to the definition LastUpdateDate. The FormatTime() function is a PPWizard macro used to calculate time variables.

#include

You can declare each definition in each template file, but a more common scenario is to put a number of definitions together in a header file. To enable the template file to make use of the definitions in the header file, it must know where to find the definitions. This is where the #include directive is used, and it tells the template file where to find the header file.

Using declared definitions

When PPWizard runs through the template file to generate the HTML page, every instance of <$definitionName> is replaced by the value assigned to the definition definitionName.

Types of definitions

1. Static definitions

Example:

#define MyName A.L. du Pisani

This definition have a value assigned to it, and does not change. Every time that the definition is called up, the same value is returned.

2. Calculated

Example:

#evaluate LastUpdateDate FormatTime("%d %B %Y")

3. Passed.

A passed definition is a definition where the user have to pass a value to the definition.

Example:

#define Standard_Header 

The variable

{$Title}

<$Standard_Header Title="SFSA Home Page">

Comments

PPWizard inline comments start with the characters ";;". Everything after the ";;" characters is ignored.

Multi-line definitions

"\" is the line continuation character where all spaces before the line continuation character is reduced to one, and the next physical line is appended, without a line break.

Example:

#define MultiLine \
This is a multi line definition

Result: Definition MultiLine is assigned the value "This is a multi line definition"

"%\" is the line continuation character where the next physical line is appended, with an explicit line break.

Example:

#define TwoLine This is line one %\
This is line two

Result: Definition TwoLine is assigned the value
"This is line one
This is line two"

It is possible to use both line continuation characters in a single definition.

Extended usage example

The HTML Header

Once I started to look at my current pages, I saw that the HTML HEAD portions was similar, and I started to look for a definition that would cover all cases.

I ended up with the following set of definitions:

#evaluate FileUpdateDateTime    FormatTime("%Y-%m-%dT%T")
#define ImagePath               Images
#define HTML_Definition         
#define Head_Charset            
#define Head_AuthorInfo         
#define Head_Copyright          
#define Head_Date               
#define Head_StyleSheet         
#define Head_Favicon            

; Standard HTML Header, as used in all generated pages. TITLE and KEYWORDS are
; passed parameters

#define Standard_Header                                               \
<$HTML_Definition>                                           %\
<HTML lang=en>                                               %\
<HEAD>                                                       %\
<TITLE>{$Title}                                    %\
<$Head_AuthorInfo>                                         %\
<$Head_Charset>                                            %\
<META name="keywords" lang="en" content="{$Keywords}">     %\
<$Head_StyleSheet>                                         %\
<$Head_Favicon>                                            %\
<$Head_Copyright>                                          %\
<$Head_Date>                                               %\
</HEAD>

All of these definitions are stored in a common header file.

Comments on the definition

The HTML 4.01 standard recomend that the date and time of the last update to the HTML page be inserted into the HTML HEAD. The format is specified in ISO8601, and the specific format used is "YYYY-MM-DDThh:mm:ssTZD". 4 digit year, 2 digit month, 2 digit day, a T to seperate the date and time portion, 2 digit hour, 2 digit minute, 2 digit second, and a time zone designator, which for me is "+02:00"; 2 hours east of GMT.

The definition FileUpdateDateTime is the calculated definition of the current date and time, in the above format, without the time zone designator. This definition is used in the definition Head_Date, where the time zone designator is added.

I have put all of the images used on the web site into an Image sub directory. I declared the ImagePath definition once, and used it every time I refer to an image resource. Should I need to change the path to the Image directory, I only need to change the ImagePath definition once to change it everywhere.

I declared a number of definitions, used only in the main HTML HEAD definition. This may be redundant, but I wanted an HTML HEAD definition that was clear and easy to understand.

For internationalization purposes, I declared the language used and the display character encoding set explicitely.

Most of the other definitions should be self explanetory.

The Title and Keywords files are to be passed by the user, once per template page.

Usage

To use the above definition, each of my template files start with the following lines of code:

; Standard definitions
#include common.ih

; Standard element - HTML HEAD definition
<$Standard_Header Title="SFSA Home Page" Keywords="Science Fiction, SF, short story">

Where common.ih is the name of the PPWizard header file in which I store all common definitions, and I change the values passed in the Title and Keywords variables to reflect the current page's information.

Result

This results in the following HTML code being generated:

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
 "http://www.w3c.org/TR/html4/loose.dtd">
<HTML lang=en>
<HEAD>
<meta name="GENERATOR" content="PPWIZARD version 03.268 on OS/2, FREE tool for Windows, OS/2, DOS
 and UNIX by Dennis Bareis (http://www.labyrinth.net.au/~dbareis/ppwizard.htm)">

<TITLE>SFSA Home Page
<META name="author" content="AL du Pisani">
<META http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
<META name="keywords" lang="en" content="Science Fiction, SF, short story">
<LINK href="sfsa.css" rel="stylesheet" type="text/css">
<LINK rel="shortcut icon" href="Images/favicon.ico" type="image/x-icon">
<META name="copyright" content="© 1999, 2000, 2001, 2002, 2003, 2004 SFSA">
<META name="date" content="2004-01-16T13:13:38+02:00">
</HEAD>

As you can see, PPWizard adds one line to the header, where it tell you what product generated the page, version, and where to get the software.

Conclusion

In the next article I will look at more standard page elements, where a single element can be used to define the entire look and feel of a page.

Resources

PPWizard: Get the newest version of the program and the documentation from the website of Dennis Bareis

HTML 4.01 and CSS2 standards: Get the newest and official documentation from the World Wide Web Consortium.