The Cactus Chronicles

2. SGML+Perl ?

2.1 The problems

When I was creating the Cactus pages, I wanted to do it in a way that would make it easy to administrate the whole site. Writing the pages in plain HTML had several drawbacks:

• Changing the look of the whole site would require editing ALL pages, a tedious task.
• Writing new pages would require me to write the same "format" code (that is for headers, background etc.) again and again.
• I could not print the pages in an easy way. Printing is important to me, because as you can see, the different sections of this site could form stand-alone articles. Especially for the Hellenic Experiences where I thought that when they reached a certain size, they could form a usefull handbook for greek Linux users.
• I wanted to include the Hellenic-HOWTO, but formating it to look like the rest of the site would take a lot of time.

I do not know if there are any free www administartion tools for Linux that could help me solve the above problems. That's why I decided to create my own.

2.2 The tools.

I had written a small part of the Hekkenic-HOWTO, so I was familliar with SGML. I decided to write the pages in SGML and then use the SGML-Tools package to convert them to HTML. That would be easy.

However, it was not enough; the result was of very poor aesthetic. I wanted my pages to have a simple look, and fiew graphics (=minimal download time) but that was too spartian. I looked at the generated HTML code and found out that it followed a well defined structure. If I could just write a program to change some HTML tags here and there, I have the desired result.

This proccess required patern scanning and the natural candidate for the programming language was Perl. I had no experience with Perl, but I had written a couple of report generators in AWK (another pattern scanner...) for my company, and after studying the Perl man pages I thought I knew enough to start writing my formating program which I called frmt.

2.3 The Look and Feel.

Before writing frmt, I had to define the desired look'n'feel. This had to be simple, since I rarely like pages full of whistles and bells. I think that such pages require professional graphic-design skills (I now I do not have them), a high transfer rate or extra-patient visitors and a high-end commercial browser (if you include java applets and/or JavaScript and other exotic features).

The decided look is simple as you can see, yet nice and functional. It has the followinig elements:

• A simple background image which is just a little over 1K.
• The Cactus logo which is also used as a link to the main page.
• The horizontal bar containing the "Previous-Next-Table of Contents" icons. The color of those icons change depending whether they are links or not.
• A 1x2 table. The first column contains a shortened version of the Tbale of Contents and the second column contains the actual text.
• In the end, I added the navigation icons at the top of the page. They are not absolutely neccesary, but I think they are useful and improve the aesthetic of the pages...

2.4 frmt the Formater

I then wrote frmt. As you can see it is very simple; I told you, this is my first Perl program!

sgml2html parses an SGML file and creates a number of HTML files, each one containing a section of the document. Suppose you call sgml2html on a file named test.sgml:

sgml2html test.sgml

The result is a number of files named test.html, test-1.html, test-2.html and so on, depending on the number of setions test.sgml has. The first file, test.html is important because it contains the Table of Contents.

frmt is called with one parameter, the name of the sgml file without the etenssion, like this:

frmt test

frmt first parses the file test.html and svaes in the list @toc an outline of the Table of Contents. It then parses all files generated by sgml and make the neccessary changes. The original files are saved with the extenssion .old and the newly created files take their places.

It should be made clear that frmt is not a general purpose tool; It can only parse sgml2html generated files and the result is what I call Cactus-format. Even so, it does its job.

2.5 The Makefile

Right now, the Cactus Site is created from 3 sgml files and several icons. In order to automate the whole procces, I wrote a Makefile which parses the sgml files with sgml2html, uses frmt to format the produced html files then copies the html files and the icons in my cactus directory. I then upload the cactus directory to my ISP and I'm done!